= Use-case model =

== Actors / Roles ==

'''Visitor''' – Anyone using EduBerza without an account, who can look at public market
information, create an account, and log in.

'''Trader''' – A registered, logged-in user who deposits virtual funds, places market buy and
sell orders, follows the value of their portfolio, and keeps a watchlist of assets they want to
monitor.

'''Market Simulator''' – An external automated system (the bot in `bots/`) that writes simulated
trades and candles into the database so prices move without a connection to a real exchange.

== Use-Cases ==

=== Visitor ===

 * [wiki:UseCase0001 UC0001] – '''Register new account''' – Visitor creates an account with a
   unique username and e-mail; the password is stored as a SHA-256 hash.
 * [wiki:UseCase0002 UC0002] – '''Log in''' – Visitor authenticates with username and password so
   the system treats every following action as a Trader.

=== Trader ===

 * [wiki:UseCase0003 UC0003] – '''Deposit virtual funds''' – Trader tops up their virtual cash
   balance; the user row and the ledger are written in one transaction.
 * [wiki:UseCase0004 UC0004] – '''Place market BUY order''' – Trader buys a crypto asset at the
   current market price, which debits cash and upserts the holding at a running weighted-average
   price.
 * [wiki:UseCase0005 UC0005] – '''Place market SELL order''' – Trader sells part or all of a
   holding at the current market price, which credits cash and preserves the cost basis.
 * [wiki:UseCase0006 UC0006] – '''View portfolio and transaction history''' – Trader inspects
   current holdings, unrealised P/L, cash balances and the most recent ledger entries.
 * [wiki:UseCase0007 UC0007] – '''Manage watchlist''' – Trader lists, adds and removes crypto
   assets on a personal watchlist, where adding an asset already on the list is a no-op.

=== Market Simulator ===

The Market Simulator initiates no use case of its own. It participates in
[wiki:UseCase0004 UC0004] and [wiki:UseCase0005 UC0005] indirectly, by keeping
`project.market_trades` populated so that `project.v_latest_prices` returns a current price for
every active market.

== Use-case model diagram ==

{{{#!comment
The diagram is optional for P3. Attach the exported image to this wiki page as
use_case_diagram.png and then replace this comment with:

[[Image(use_case_diagram.png)]]
}}}

== Detailed Use-Cases ==

The following use-cases are documented in detail, with SQL tested against the P2 database:

 * [wiki:UseCase0001 UseCase0001] – Visitor registers a new account
 * [wiki:UseCase0002 UseCase0002] – Visitor logs in
 * [wiki:UseCase0003 UseCase0003] – Trader deposits virtual funds
 * [wiki:UseCase0004 UseCase0004] – Trader places a market BUY order
 * [wiki:UseCase0005 UseCase0005] – Trader places a market SELL order
 * [wiki:UseCase0006 UseCase0006] – Trader views portfolio and transaction history
 * [wiki:UseCase0007 UseCase0007] – Trader manages a watchlist

== Realization details on selection of the most important use cases ==

This is a solo project, so '''at least 3 use cases''' are required. '''7 use cases''' are
documented, for a safety margin. All seven are implemented in the P4 prototype; see `server/`
for the Go source and [wiki:PrototypeImplementation] for the documented runs.

||=Use case=||=Importance=||=Why it was selected=||
||[wiki:UseCase0001 UC0001 – Register]||High||Nothing else works without it; demonstrates `INSERT` with a uniqueness check.||
||[wiki:UseCase0002 UC0002 – Log in]||High||Authenticates every Trader action; demonstrates `SELECT` with parameter binding.||
||[wiki:UseCase0003 UC0003 – Deposit]||High||Shows a multi-row transaction: `UPDATE users` plus `INSERT INTO transactions`.||
||[wiki:UseCase0004 UC0004 – Buy]||Very high||Core of the exchange: `INSERT orders`, `UPDATE users`, upsert `holdings`, ledger entry, market trade.||
||[wiki:UseCase0005 UC0005 – Sell]||Very high||Dual of Buy; demonstrates row-level `FOR UPDATE` locking and cost-basis bookkeeping.||
||[wiki:UseCase0006 UC0006 – Portfolio]||High||Demonstrates joins over `holdings`, `markets` and `crypto`, and the `v_portfolio` view.||
||[wiki:UseCase0007 UC0007 – Watchlist]||Medium||Demonstrates N–M relation handling and `ON CONFLICT` upsert semantics.||