Context Navigation

-              ra531b45
+              ref1c1c7
 # Build Instructions
 How to compile, configure, run and test the EduBerza prototype.
 Linked from [PrototypeImplementation](PrototypeImplementation.md).
+This page explains how to compile, configure, run and test the EduBerza prototype.
+It is linked from [PrototypeImplementation](PrototypeImplementation.md).
 ## Development environment description
 …
 | Tool        | Version tested        | Needed for                                                    |
 |-------------|-----------------------|---------------------------------------------------------------|
+| Go          | 1.26 (1.25+ works)    | Building `server/` (the CLI) and `bots/` (the market bot).     |
+| PostgreSQL  | 16                    | The database. Docker image or the faculty server.              |
+| Docker      | any recent            | Optional — brings up a local PostgreSQL in one command.        |
+| `psql`      | any                   | Optional — running the SQL scripts by hand.                    |
+| Java        | 21 (8+ works)         | Optional — only to open/edit the ER diagram in TerraER.         |
+| DBeaver     | any recent            | Optional — only to export `relational_schema.jpg`.              |
+Nothing else has to be installed. The only third-party Go dependency
+(`github.com/lib/pq`, the PostgreSQL driver) is fetched automatically by
+`go build` from `go.mod`/`go.sum`.
+| Go          | 1.26.0 (`go.mod` asks for 1.25 or newer) | Building `server/` (the CLI) and `bots/` (the market bot). |
+| PostgreSQL  | 16.3 (Docker container) | The database. Either the local Docker container or the faculty server. |
+| Docker + Docker Compose | any recent | Optional. Starts a local PostgreSQL with one command. |
+| `psql`      | 16                    | Optional. Only for running the SQL scripts by hand.            |
+| Java        | 21 (8+ works)         | Optional. Only to open or edit the ER diagram in TerraER.      |
+| DBeaver     | any recent            | Optional. Only to export `relational_schema.jpg`.              |
+About the PostgreSQL version: `docker-compose.yml` uses the image `postgres` without a version
+tag. Docker therefore starts whatever version of the official image it has pulled. On the
+machine where the prototype was tested, that was PostgreSQL 16.3. The only extension the schema
+needs is `pgcrypto` (`CREATE EXTENSION IF NOT EXISTS pgcrypto`). It ships with PostgreSQL and is
+included in the official image.
+You do not need to install anything else. The only third-party Go library is the PostgreSQL
+driver `github.com/lib/pq`. `go build` downloads it automatically, at the version pinned in
+`go.mod` and `go.sum`.
 ## Build instructions
 All commands run from the repository root.
+Run all commands from the repository root.
 ### 1. Configure the database connection
 …
 ```
 The defaults in `.env.example` match the bundled Docker setup. To use the
+faculty database instead, either edit `.env` or pass the values as real
 environment variables — those take precedence over the file:
+The defaults in `.env.example` (`localhost:5433`, user `bp_project`, database `bp_database`)
+match the bundled Docker setup. To use the faculty database instead, edit `.env`, or pass the
+values as real environment variables. Real environment variables take precedence over the file:
 ```sh
 …
 ```
+`.env` is deliberately not committed (see `.gitignore`) because it holds a
+password.
+`.env` is not committed on purpose (see `.gitignore`), because it holds a password.
 ### 2. Start PostgreSQL
 …
 ```
 Skip this step if you are pointing at the faculty database.
+Skip this step if you use the faculty database.
 ### 3. Build
 …
 ```
+This runs `server/db/schema_creation.sql` and then `server/db/data_load.sql`.
+Both are **compiled into the binary** (`go:embed`), so `-init` works regardless
+of which directory you launch it from. It is destructive and idempotent — it
+drops and recreates the whole `project` schema, so it is also the reset button
+if a demo goes wrong. To reload only the data, keeping the schema:
+```sh
+./eduberza -load-data
+```
+The equivalent with `psql`, if you prefer to watch the statements run:
+This runs `server/db/schema_creation.sql` and then `server/db/data_load.sql`. It logs
+`Running schema_creation.sql ...`, `Running data_load.sql ...` and `Database initialised.`,
+then prints:
+```
+Schema initialised. Re-run without -init to start the CLI.
+```
+Both scripts are **compiled into the binary** (`go:embed`), so `-init` works from any
+directory. It is destructive and can be run again any number of times: it drops and recreates
+the whole `project` schema, so it also resets everything if a demo goes wrong. To reload only
+the data and keep the schema:
+```sh
+./eduberza -load-data          # prints "Sample data reloaded."
+```
+If you prefer to watch the statements run, the same can be done with `psql`:
 ```sh
 …
 ```
+Seed accounts — all with the password `test123`:
+| Username  | Starting state                                        |
+|-----------|-------------------------------------------------------|
+| `alice`   | 8250.00 USD cash, holds 0.5 ETH — best demo account   |
+| `bob`     | 5000.00 USD cash, no positions                        |
+| `charlie` | 2500.00 USD cash, no positions                        |
+### 6. Optional — run the market simulation bot
+In a second terminal:
+```sh
+go run ./bots
+```
+The bot walks the price of every active market, inserts a row into
+`market_trades` on each tick and upserts the current 1-minute candle. Prices in
+the CLI change while it runs, because the current price is always read from the
+most recent trade (`v_latest_prices`), never from a stored column.
+### 7. Optional — richer data for the P6 reports
+`data_load.sql` only seeds a few minutes of trade history, which is not enough
+for the [top traders](../P6-AdvancedReports/AdvancedReports.md#top-traders-by-realized-performance)
+or [market performance](../P6-AdvancedReports/AdvancedReports.md#market-performance-leaderboard)
+reports (menu `[10]`/`[11]`) to show more than a single period. To see them do
+something more interesting, load five quarters of synthetic history on top:
+### 6. Optional: run the market simulation bot
+In a second terminal, also from the repository root (the bot reads `.env` from the current
+directory):
+```sh
+go run ./bots                  # add -interval 1s for faster ticks; the default is 3s
+```
+On every tick the bot moves the price of every active market by a small random step, inserts a
+row into `market_trades` and updates the current 1-minute candle. Prices in the CLI change
+while it runs, because the current price is always read from the most recent trade
+(`v_latest_prices`) and never from a stored column. Leave the bot off if you want the exact
+numbers in the tests below.
+### 7. Optional: richer data for the P6 reports
+`data_load.sql` seeds only a few minutes of trade history. That is not enough for the
+[top traders](../P6-AdvancedReports/AdvancedReports.md) and
+[market performance](../P6-AdvancedReports/AdvancedReports.md) reports (menu `[10]` and `[11]`)
+to show more than one period. To see more interesting results, load five quarters of synthetic
+history on top:
 ```sh
 …
 ```
 It is deliberately not part of `-init`/`-load-data` — see the header of
 [`reports_demo_data.sql`](../../server/db/reports_demo_data.sql) for why — so
 running it never changes the balances the smoke test below checks.
+This script is not part of `-init` or `-load-data` on purpose. The header of
+[`reports_demo_data.sql`](../../server/db/reports_demo_data.sql) explains why. Running it never
+changes the balances that the tests below check.
 ## Testing instructions
+### How to launch and log in
+Start the prototype with `./eduberza` after steps 1–4. The sample data creates three test
+users. All of them have the password **`test123`**:
+| Username  | Starting state after `-init` |
+|-----------|------------------------------|
+| `alice`   | 8250.00 USD available (1750.00 invested), holds 0.5 ETH bought at 3500.00. Watchlist "Favorites": BTC, ETH, SOL. Best demo account. |
+| `bob`     | 5000.00 USD available, no crypto. Watchlist "Bobs Picks": BTC, DOGE. |
+| `charlie` | 2500.00 USD available, no crypto, no watchlist yet. |
+The five sample markets are ADA, BTC, DOGE, ETH and SOL, all quoted in USD. Their starting
+last prices are 0.45375, 67140, 0.122, 3520 and 166.1.
 ### Mini-guide to the application
+The CLI has two menus. Before logging in: **Register**, **Login**,
+**Browse markets**. After logging in: **View balance**, **Deposit virtual
+funds**, **Browse markets**, **Place market BUY order**, **Place market SELL
+order**, **View portfolio**, **View transaction history**, **Manage watchlist**,
+**Logout**, and two [P6](../P6-AdvancedReports/AdvancedReports.md) reports:
+**Report: top traders** and **Report: market performance**.
+You never have to remember an identifier. Markets are always printed as a
+numbered list with their current price before you are asked which one you want,
+and assets are referred to by symbol (`BTC`, `ETH`, …), never by database id.
+You always answer with the number of a menu option. When you have to choose a market, a
+holding or a crypto, the prototype prints a numbered list and you type the number from that
+list. You never type an id or a symbol. A number that is not in the list is refused with
+`Invalid choice, enter a number from 1 to N.`
+**Menu before login**
+| Option | What it does and how to use it |
+|--------|--------------------------------|
+| `[1] Register` | Enter a username, an e-mail (must contain `@`), your full name and a password (at least 6 characters). You get `Account created. You can now log in.`, or `Invalid email.`, `Password must be at least 6 characters.` or `Username or email already taken.` A new account starts with 0 USD. |
+| `[2] Login` | Enter your username and password. You get `Login successful.` and the second menu. A wrong password and an unknown username both give `Invalid credentials.` |
+| `[3] Browse markets` | Prints the numbered list of markets with their last price. |
+| `[0] Exit` | Ends the program. |
+**Menu after login** (headed `--- Logged in as <username> ---`)
+| Option | What it does and how to use it |
+|--------|--------------------------------|
+| `[1] View balance` | Shows the available, invested and total USD. |
+| `[2] Deposit virtual funds` | Enter an amount in USD. It must be a positive number, otherwise you get `Invalid amount.` You get `Deposited 500.0000 USD.` |
+| `[3] Browse markets` | Same list as before login. |
+| `[4] Place market BUY order` | Lists all markets, numbered, with their last price. Type the number at `Market #:`. The prototype shows the latest price. Type the quantity. You get `Order executed: buy …` or `Insufficient funds: need …, have …`. |
+| `[5] Place market SELL order` | Lists only the cryptos you hold, numbered, with columns `Held` and `Free to sell`. Type the number at `Holding #:`, then the quantity. You get `Order executed: sell …` or `Insufficient holding: …`. If you hold nothing, you get `you hold no crypto that is free to sell`. |
+| `[6] View portfolio` | One row per crypto you hold: quantity, reserved, available, average buy price, current price, value and unrealised P/L. Then your cash, portfolio value and net worth. |
+| `[7] View transaction history` | Your last 20 ledger entries (deposits, buys, sells), newest first. |
+| `[8] Manage watchlist` | Opens a submenu: `[1] List items` shows your watchlist with last prices. `[2] Add crypto` lists, numbered, the cryptos not on it yet; type a number. `[3] Remove crypto` lists, numbered, the cryptos on it; type a number. `[0] Back` returns. A user without a watchlist gets one named "Favorites" the first time. |
+| `[9] Logout` | Back to the first menu. |
+| `[10] Report: top traders` | P6 report. Enter a start date (inclusive) and an end date (exclusive) as `YYYY-MM-DD`. |
+| `[11] Report: market performance` | P6 report, with the same two dates. |
+| `[0] Exit` | Ends the program. |
 ### End-to-end smoke test
+Verified on 2026-09-16 against PostgreSQL 16 with freshly loaded sample data.
+Expected values are exact.
+. `./eduberza -init` — prints `Database initialised.`
+. `./eduberza`, then `[2] Login` → `alice` / `test123` → `Login successful.`
+. `[6] View portfolio` → one row: `ETH 0.5000` reserved 0.0000, available
+.5000, at avg 3500.000000, current 3520.000000, value 1760.0000,
+   unrealised P/L `+10.0000`. Cash available 8250.0000, net worth 10010.0000.
+. `[4] Place market BUY order` → `BTC` → `0.01` →
+These values were checked on 2026-09-24 against freshly loaded sample data (PostgreSQL 16.3),
+with the bot not running. The expected values are exact.
+. `./eduberza -init` prints `Schema initialised. Re-run without -init to start the CLI.`
+. `./eduberza`, then `2` (Login), then `alice` / `test123` gives `Login successful.`
+. `6` (View portfolio) shows one row: `ETH`, quantity 0.5000, reserved 0.0000, available
+.5000, average buy 3500.000000, current 3520.000000, value 1760.0000, unrealised P/L
+   `+10.0000`. Cash available is 8250.0000 and net worth is 10010.0000.
+. `4` (BUY). The market list shows `1 ADA`, `2 BTC`, `3 DOGE`, `4 ETH`, `5 SOL`. Type `2` at
+   `Market #:`, then `0.01` at `Quantity:`. The result is
    `Order executed: buy 0.0100 BTC @ 67140.000000 (notional 671.4000 USD)`.
+. `[6] View portfolio` → now BTC *and* ETH, total value 2431.4000, cash
+.6000 (= 8250.00 − 671.40), net worth still 10010.0000.
+. `[5] Place market SELL order` → `ETH` → `0.5` →
+. `6` (View portfolio) now shows BTC *and* ETH, with total value 2431.4000, cash 7578.6000
+   (= 8250.00 − 671.40), and net worth still 10010.0000.
+. `5` (SELL). The holdings list shows `1 BTC` (held 0.0100) and `2 ETH` (held 0.5000). Type
+   `2` at `Holding #:`, then `0.5`. The result is
    `Order executed: sell 0.5000 ETH @ 3520.000000 (notional 1760.0000 USD)`.
+. `[7] View transaction history` → deposit, buy, buy, sell, newest first.
+. `[8] Manage watchlist` → `[1] List items` → alice's `Favorites` contains
+   BTC, ETH, SOL with live prices.
+. `[9] Logout`, then `[0] Exit`.
+. `7` (View transaction history) lists, newest first: the `sell` (+1760.0000), the `buy` of
+   BTC (−671.4000), then the two rows from the sample data, which have the same timestamp:
+   `deposit` 10000.0000 "Initial virtual deposit" and `buy` −1750.0000 "Market buy 0.5 ETH @
+.00".
+. `8` (Manage watchlist), then `1` (List items), shows alice's watchlist with BTC, ETH and SOL
+   and their last prices. Then `2` (Add crypto) lists `1 ADA` and `2 DOGE`; type `1` and you get
+   `Added ADA.` Then `0` (Back).
+. `9` (Logout), then `0` (Exit).
 ### Testing the failure paths
+These matter more than the happy path, because they are what proves the
+transactions actually roll back:
+- **Insufficient funds:** log in as `charlie` (2500 USD) and try to buy `1` BTC.
+  Expect `Insufficient funds: need 67140.0000, have 2500.0000` and *no* change
+  to any table — no order row, no ledger entry, no holding.
+- **Insufficient holding:** as `bob` (no positions), try to sell `1` ETH.
+  Expect `Insufficient holding: trying to sell 1.0000, available 0.0000 (of
+.0000 held, 0.0000 reserved)`.
+- **Two sell orders racing for the same crypto:** give `alice` a 2 BTC holding
+  and start two `eduberza` processes at once, each selling `1.5` BTC (together
+BTC, more than she has). Expect exactly one `Order executed`, and the
+  other `Insufficient holding` reading the post-commit quantity — see
+  [UseCase0005Implementation](UseCase0005Implementation.md) for the exact
+  transcript. This is the concurrency guarantee that
+  `holdings.reserved_quantity` and the `SELECT ... FOR UPDATE` lock together
+  provide.
+These matter more than the happy path, because they prove that the transactions really roll
+back and that invalid choices are refused:
+- **Insufficient funds:** log in as `charlie` (2500 USD). Choose `4`, market `2` (BTC),
+  quantity `1`. Expect `Insufficient funds: need 67140.0000, have 2500.0000` and *no* change to
+  any table: no order row, no ledger entry, no holding.
+- **Insufficient holding:** on fresh data (`./eduberza -load-data`), log in as `alice`. Choose
+  `5`; the list shows only `1 ETH` (held 0.5000, free 0.5000). Choose `1`, quantity `5`. Expect
+  `Insufficient holding: trying to sell 5.0000, available 0.5000 (of 0.5000 held, 0.0000 reserved)`.
+- **Nothing to sell:** as `bob` (no crypto), choose `5`. The holdings list is empty, and you
+  get `you hold no crypto that is free to sell` without being asked for a number.
+- **Invalid choice from a list:** in any list (for example `8`, then `3` Remove crypto), type a
+  number larger than the list. Expect `Invalid choice, enter a number from 1 to N.`
+- **Invalid deposit:** choose `2` and enter `-50`. Expect `Invalid amount.`
 - **Duplicate registration:** register with username `alice`. Expect
   `Username or email already taken.`
+- **Invalid e-mail:** register with an e-mail without `@`. Expect `Invalid email.`
 - **Wrong password:** log in as `alice` with any wrong password. Expect
+  `Invalid credentials.` — and note the same message for an unknown username, so
+  the prototype does not leak which accounts exist.
+  `Invalid credentials.` An unknown username gives the same message, so the prototype does not
+  reveal which accounts exist.
+The concurrency guarantee of the sell path (two processes selling the same crypto at the same
+moment) cannot be reproduced by typing into two terminals, because each order commits within
+milliseconds. It is described in [UseCase0005Implementation](UseCase0005Implementation.md).
 ### For the public presentation
 Demo with `alice` (already has a position, so the portfolio screen is not
+empty), and register a brand-new account live to show UC0001. Run the bot in a
 background terminal so the prices visibly move between two portfolio refreshes.
+Demo with `alice`. She already has a position, so the portfolio screen is not empty. Register a
+brand-new account live to show UC0001. Run the bot in a background terminal so the prices
+visibly move between two portfolio refreshes.
 ## Editing the ER diagram
+TerraER is a third-party tool and is deliberately **not** committed to this
+repository. Download the teacher's build from
+<https://bazi.finki.ukim.mk/resources/Software/> and run it:
+```sh
+java -jar TerraER3.11.jar     # then File → Open → docs/ERModel_v01.xml
+```
+Save new versions as `ERModel_v02.xml`, `ERModel_v03.xml`, … and export a
+matching PNG for each. TerraER does not add the extension itself — type
+`.xml` explicitly or the file will not reopen.
+TerraER is a third-party tool and is **not** committed to this repository on purpose. Download
+the teacher's build from <https://bazi.finki.ukim.mk/resources/Software/> and run it:
+```sh
+java -jar TerraER3.11.jar     # then File → Open → docs/P1-ConceptualModel/ERModel_v03.xml
+```
+The current version is `ERModel_v03.xml`. Save new versions as `ERModel_v04.xml` and so on,
+and export a matching PNG for each. TerraER does not add the extension itself: type `.xml`
+yourself, or the file will not reopen.
 ## Up-to-date source code
 The repository is pushed to the FINKI DEVELOP git server; see the Repositories
 section in EPRMS for the clone URL and credentials.
+The repository is pushed to the FINKI DEVELOP git server. The clone URL and credentials are in
+the Repositories section in EPRMS.
 ### About the source code
+- All source needed to run the prototype is in this repository: the CLI
+  (`server/`), the market bot (`bots/`), the DDL script and the sample-data
+  script (`server/db/`).
+- Third-party Go libraries are **not** vendored — `go build` downloads
+  `github.com/lib/pq` using the pinned versions in `go.mod` and `go.sum`.
+- Third-party executables are **not** committed. `.gitignore` excludes `*.jar`;
+  TerraER is downloaded from the URL above.
+- No third-party images, styles or frameworks are used, and there are no
+  images in the prototype at all — the interface is text.
+- All the source needed to run the prototype is in this repository: the CLI (`server/`), the
+  market bot (`bots/`), the DDL script and the sample-data script (`server/db/`).
+- Third-party Go libraries are **not** vendored. `go build` downloads `github.com/lib/pq` at
+  the versions pinned in `go.mod` and `go.sum`.
+- Third-party executables are **not** committed. `.gitignore` excludes `*.jar`, and TerraER is
+  downloaded from the URL above.
+- No third-party images, styles or frameworks are used. The prototype has no images at all;
+  the interface is text.

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset ef1c1c7 for docs/P4-Prototype/BuildInstructions.md

Legend:

docs/P4-Prototype/BuildInstructions.md

Download in other formats: