Changeset df05838 for docs/P4-Prototype


Ignore:
Timestamp:
09/11/26 11:05:54 (3 weeks ago)
Author:
Stefan <trsunovstefan@…>
Branches:
main
Children:
9577c79
Parents:
fe28254
Message:

Zip files

Location:
docs/P4-Prototype
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed

  • docs/P4-Prototype/PrototypeImplementation.md

    rfe28254 rdf05838  
    1 # Prototype Implementation
     1= Prototype Implementation =
    22
    3 The prototype is a Go command-line application in `server/` that works against
    4 the `project` schema in PostgreSQL. It implements all seven use cases from
    5 [UseCaseModel](../P3-UseCaseModel/UseCaseModel.md) — the rubric requires at least three — with
    6 every database access shown as real, executed SQL. An auxiliary program in
    7 `bots/` simulates a live market so prices move while the prototype is running.
     3The prototype is a Go command-line application in
     4[https://github.com/StefanTrsunov/bp/tree/main/server server/] that works against the `project`
     5schema in PostgreSQL. It implements all seven use cases from
     6[https://github.com/StefanTrsunov/bp/blob/main/docs/P3-UseCaseModel/UseCaseModel.md UseCaseModel]
     7– the rubric requires at least three – with every database access shown as real, executed SQL.
     8An auxiliary program in [https://github.com/StefanTrsunov/bp/tree/main/bots bots/] simulates a
     9live market so prices move while the prototype is running.
    810
    9 Build, configure, run and test instructions: [BuildInstructions](BuildInstructions.md).
     11Build, configure, run and test instructions:
     12[https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/BuildInstructions.md BuildInstructions].
    1013
    11 ## Implemented use-cases
     14All pages listed below, together with the screenshots of each run, are kept in the project's
     15GitHub repository, [https://github.com/StefanTrsunov/bp StefanTrsunov/bp], under
     16`docs/P4-Prototype/`.
    1217
    13 | Page | Use-case | Source |
    14 |------|----------|--------|
    15 | [UseCase0001Implementation](UseCase0001Implementation.md) | Register a new account | `server/auth.go` |
    16 | [UseCase0002Implementation](UseCase0002Implementation.md) | Log in | `server/auth.go` |
    17 | [UseCase0003Implementation](UseCase0003Implementation.md) | Deposit virtual funds | `server/account.go` |
    18 | [UseCase0004Implementation](UseCase0004Implementation.md) | Place market BUY order | `server/trade.go` |
    19 | [UseCase0005Implementation](UseCase0005Implementation.md) | Place market SELL order | `server/trade.go` |
    20 | [UseCase0006Implementation](UseCase0006Implementation.md) | View portfolio and history | `server/portfolio.go` |
    21 | [UseCase0007Implementation](UseCase0007Implementation.md) | Manage watchlist | `server/watchlist.go` |
     18== Implemented use-cases ==
    2219
    23 Each page mirrors its P3 use-case page and adds the actual SQL emitted by the Go
    24 code plus a screenshot of the corresponding run against the live database.
     20||=Page=||=Use-case=||=Source=||
     21||[https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/UseCase0001Implementation.md UseCase0001Implementation]||Register a new account||[https://github.com/StefanTrsunov/bp/blob/main/server/auth.go server/auth.go]||
     22||[https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/UseCase0002Implementation.md UseCase0002Implementation]||Log in||[https://github.com/StefanTrsunov/bp/blob/main/server/auth.go server/auth.go]||
     23||[https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/UseCase0003Implementation.md UseCase0003Implementation]||Deposit virtual funds||[https://github.com/StefanTrsunov/bp/blob/main/server/account.go server/account.go]||
     24||[https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/UseCase0004Implementation.md UseCase0004Implementation]||Place market BUY order||[https://github.com/StefanTrsunov/bp/blob/main/server/trade.go server/trade.go]||
     25||[https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/UseCase0005Implementation.md UseCase0005Implementation]||Place market SELL order||[https://github.com/StefanTrsunov/bp/blob/main/server/trade.go server/trade.go]||
     26||[https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/UseCase0006Implementation.md UseCase0006Implementation]||View portfolio and history||[https://github.com/StefanTrsunov/bp/blob/main/server/portfolio.go server/portfolio.go]||
     27||[https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/UseCase0007Implementation.md UseCase0007Implementation]||Manage watchlist||[https://github.com/StefanTrsunov/bp/blob/main/server/watchlist.go server/watchlist.go]||
    2528
    26 ## What the prototype demonstrates about the database design
     29Each page mirrors its P3 use-case page and adds the actual SQL emitted by the Go code plus a
     30screenshot of the corresponding run against the live database. The screenshots are committed
     31alongside the pages, in
     32[https://github.com/StefanTrsunov/bp/tree/main/docs/P4-Prototype/screenshots docs/P4-Prototype/screenshots/].
    2733
    28 - **The current price is never stored as a column.** It is always the price of
    29   the most recent row in `market_trades`, read through the `v_latest_prices`
    30   view. Both the user's own fills and the bot's simulated trades feed the same
    31   table, so there is exactly one definition of "the price".
    32 - **Money movements are transactional.** Buying touches five tables — `orders`,
    33   `users`, `holdings`, `transactions`, `market_trades` — inside one transaction.
    34   A failed balance check rolls the whole thing back: after a rejected purchase
    35   there is no order row, no ledger entry and no holding. This is verified in the
    36   failure-path tests in [BuildInstructions](BuildInstructions.md).
    37 - **Constraints do real work.** `UNIQUE (user_id, crypto_id)` on `holdings` is
    38   what makes the `INSERT … ON CONFLICT DO UPDATE` upsert possible, so the
    39   weighted-average entry price is recomputed by the database in one statement
    40   instead of by a read-modify-write in application code.
    41 - **No identifiers are ever typed.** Markets are listed with their prices before
    42   any choice is made, and everything else is selected by symbol.
     34== What the prototype demonstrates about the database design ==
    4335
    44 ## Known limitations
     36 * '''The current price is never stored as a column.''' It is always the price of the most recent
     37   row in `market_trades`, read through the `v_latest_prices` view. Both the user's own fills and
     38   the bot's simulated trades feed the same table, so there is exactly one definition of "the
     39   price".
     40 * '''Money movements are transactional.''' Buying touches five tables – `orders`, `users`,
     41   `holdings`, `transactions`, `market_trades` – inside one transaction. A failed balance check
     42   rolls the whole thing back: after a rejected purchase there is no order row, no ledger entry
     43   and no holding. This is verified in the failure-path tests in
     44   [https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/BuildInstructions.md BuildInstructions].
     45 * '''Constraints do real work.''' `UNIQUE (user_id, crypto_id)` on `holdings` is what makes the
     46   `INSERT … ON CONFLICT DO UPDATE` upsert possible, so the weighted-average entry price is
     47   recomputed by the database in one statement instead of by a read-modify-write in application
     48   code.
     49 * '''No identifiers are ever typed.''' Markets are listed with their prices before any choice is
     50   made, and everything else is selected by symbol.
    4551
    46 Deliberately out of scope for a first prototype, and the natural content of the
    47 later phases:
     52== Known limitations ==
    4853
    49 - Only `market` orders execute. `limit` is accepted by the schema
    50   (`orders.type`) but the matching logic is not implemented.
    51 - Passwords are SHA-256 without a salt. Adequate to demonstrate that the
    52   password itself is never stored; not adequate for real use. A proper
    53   password hash belongs in P9 (security).
    54 - Money is handled as `float64` in Go while the database columns are `numeric`.
    55   All arithmetic that must be exact — the weighted average — is done in SQL for
    56   that reason, but the Go side would need a decimal type for real use.
    57 - There is no connection pooling configuration and no explicit isolation level;
    58   both are P8 topics.
     54Deliberately out of scope for a first prototype, and the natural content of the later phases:
     55
     56 * Only `market` orders execute. `limit` is accepted by the schema (`orders.type`) but the
     57   matching logic is not implemented.
     58 * Passwords are SHA-256 without a salt. Adequate to demonstrate that the password itself is
     59   never stored; not adequate for real use. A proper password hash belongs in P9 (security).
     60 * Money is handled as `float64` in Go while the database columns are `numeric`. All arithmetic
     61   that must be exact – the weighted average – is done in SQL for that reason, but the Go side
     62   would need a decimal type for real use.
     63 * There is no connection pooling configuration and no explicit isolation level; both are P8
     64   topics.
     65== AI usage ==
     66
     67AI was used in this phase and is logged in full, per the course rule for P1 onward.
     68
     69 * '''Phase log:'''
     70   [https://github.com/StefanTrsunov/bp/blob/main/docs/P3-UseCaseModel/UseCaseModelAIUsage.md UseCaseModelAIUsage.md]
     71   – service used, what the AI produced, and what I decided myself.
     72 * '''Full conversation transcript:'''
     73   [https://github.com/StefanTrsunov/bp/blob/main/docs/P1-ConceptualModel/ERModelAIUsage.md ERModelAIUsage.md]
     74   – the same conversation produced the P1–P4 artefacts, so the complete prompt/response log is
     75   kept in one place. Direct links:
     76   [https://github.com/StefanTrsunov/bp/blob/main/docs/P1-ConceptualModel/ERModelAIUsage.md#session-1--2026-04-21 Session 1 – 2026-04-21],
     77   [https://github.com/StefanTrsunov/bp/blob/main/docs/P1-ConceptualModel/ERModelAIUsage.md#session-2--2026-08-06--2026-08-07 Session 2 – 2026-08-06/07].
     78
     79'''Service:''' Claude Code (Anthropic), https://claude.com/claude-code – Claude subscription,
     80model Claude Opus 4.7 (1M context).
     81
     82'''In short:''' the AI proposed the actor taxonomy and drafted the seven use cases with their SQL
     83in session 1. In session 2 the use-case model itself was '''not''' changed – the only work was
     84re-executing every scenario, including the failure paths, against a live PostgreSQL 16 database.
     85
     86== AI usage ==
     87
     88AI was used in this phase and is logged in full, per the course rule for P1 onward.
     89
     90 * '''Phase log:'''
     91   [https://github.com/StefanTrsunov/bp/blob/main/docs/P4-Prototype/PrototypeImplementationAIUsage.md PrototypeImplementationAIUsage.md]
     92   – service used, the bugs found and fixed, the test evidence, and what I decided myself.
     93 * '''Full conversation transcript:'''
     94   [https://github.com/StefanTrsunov/bp/blob/main/docs/P1-ConceptualModel/ERModelAIUsage.md ERModelAIUsage.md]
     95   – the same conversation produced the P1–P4 artefacts, so the complete prompt/response log is
     96   kept in one place. Direct links:
     97   [https://github.com/StefanTrsunov/bp/blob/main/docs/P1-ConceptualModel/ERModelAIUsage.md#session-1--2026-04-21 Session 1 – 2026-04-21],
     98   [https://github.com/StefanTrsunov/bp/blob/main/docs/P1-ConceptualModel/ERModelAIUsage.md#session-2--2026-08-06--2026-08-07 Session 2 – 2026-08-06/07].
     99
     100'''Service:''' Claude Code (Anthropic), https://claude.com/claude-code – Claude subscription,
     101model Claude Opus 4.7 (1M context).
     102
     103'''In short:''' session 1 rewrote the existing Chi/HTTP backend as the CLI prototype covering
     104UC0001–UC0007 and added the market bot. Session 2 was a review pass I asked for, which found and
     105fixed three bugs – a path-resolution bug that made the documented build instructions fail, an
     106infinite loop at end of input, and an error check in the wrong order that misreported database
     107failures as "Insufficient holding" – and replaced the read-modify-write holding update with a
     108single `INSERT … ON CONFLICT DO UPDATE`.
Note: See TracChangeset for help on using the changeset viewer.