Project Documentation

.husky/pre-commit

@@ -1,2 +1,3 @@
+pnpm exec markdownlint '**/*.md' --fix --ignore node_modules
 pnpm exec lint-staged
-pnpm test
+pnpm test

.markdownlint.yml

@@ -0,0 +1 @@
+'MD013': false

.prettierrc.yml

@@ -7,4 +7,3 @@ quoteProps: as-needed
 trailingComma: none
 bracketSpacing: true
 bracketSameLine: false
-

.tool-versions

@@ -1 +1 @@
-nodejs 22.15.1
+nodejs 22.16.0

README.md

@@ -12,7 +12,7 @@
 **macOS/via `brew`**
 
 1. Install `asdf`: `brew install asdf`
-    - Note: for additional configuration options/a more detailed setup guide, see the official docs.
+   - Note: for additional configuration options/a more detailed setup guide, see the official docs.
 2. Install `asdf-nodejs`: `asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git`
 3. Install required node version: `asdf install nodejs` (must be run while within repo; .tool-versions must be visible to asdf)
 4. Install `pnpm`: `brew install pnpm`

docs/assets/architecture.d2

@@ -0,0 +1,31 @@
+user: |md
+  **User**
+
+  [Person]
+
+  Retail investors of all experience levels
+|
+user.shape: rectangle
+
+frontend: |md
+  **Frontend**
+
+  [Software System]
+
+  Primarily a data display and interface, used by users to communicate with the <br />
+  backend
+|
+frontend.shape: rectangle
+
+backend: |md
+  **Backend**
+
+  [Software System]
+
+  Hosts and serves user data and queries data from external APIs on behalf of <br />
+  the entire set of users; performs and runs analyses requests by users.
+|
+backend.shape: rectangle
+
+user <-> frontend
+frontend <-> backend

docs/assets/authentication-workflow.d2

@@ -0,0 +1,89 @@
+direction: down
+
+start: Start {
+  shape: rectangle
+  style: {
+    border-radius: 20
+    fill: grey
+  }
+}
+
+d1: |md
+  User is authenticated <br />
+  (session cookie present)
+| {
+  shape: diamond
+}
+
+n2: |md
+  Redirect to login page
+| {
+  shape: rectangle
+}
+
+n3: |md
+  Login
+| {
+  shape: rectangle
+}
+
+n8: |md
+  Register
+| {
+  shape: rectangle
+}
+
+d4: |md
+  Authentication
+| {
+  shape: diamond
+}
+
+n5: |md
+  Redirect to previous or default page
+| {
+  shape: rectangle
+}
+
+n6: |md
+  Session authenticated
+| {
+  shape: rectangle
+}
+
+n7: |md
+  Session expired
+| {
+  shape: rectangle
+}
+
+n9: |md
+  Logout
+| {
+  shape: rectangle
+}
+
+end: End {
+  shape: rectangle
+  style: {
+    border-radius: 20
+    fill: grey
+  }
+}
+
+start -> d1
+d1 -> n2: No
+d1 -> n6: Yes
+n6 -> n5
+n2 -> n3
+n3 -> d4
+n2 -> n8
+n8 -> n2
+d4 -> n6: Good credentials
+d4 -> n2: Bad credentials
+n6 -> n7: timeout
+n6 -> n9
+n9 -> n7
+n7 -> n2
+n6 -> end
+n7 -> end

docs/assets/authentication.d2

@@ -0,0 +1,29 @@
+shape: sequence_diagram
+
+client: Client
+webserver: Webserver
+backend: Backend
+
+webserver -> client: |md
+  Serve application
+|
+
+authentication: Authentication {
+  client.d1 -> backend.d1: |md
+    Credentials (password-based authentication)
+  |
+
+  backend.d1 -> client.d1: |md
+    Session cookie
+  |
+}
+
+session: Authenticated Session {
+  client.d2 -> backend.d2: |md
+    Authenticated Request
+  |
+
+  backend.d2 -> client.d2: |md
+    Response
+  |
+}

docs/assets/class-diagram.d2

@@ -0,0 +1,62 @@
+User: {
+  shape: class
+
+  -\#identifier: string
+  -watchlist: "{ [ticker: string]: Holding }"
+  +identifier: string
+  +watchlistTickers: string
+
+  +constructor(identifier string)
+  +addTicker(ticker string): boolean
+  +removeTicker(ticker string): boolean
+  +addPosition(ticker string): boolean
+  +removePosition(ticker string): boolean
+  +getHolding(ticker string): Holding
+}
+
+Holding: {
+  shape: class
+
+  +ticker: string
+  -\#positions: "Position[]"
+  +totalInvestment: number
+  +totalQuantity: number
+  +averageCost: number
+  +openPositions: number
+
+  +constructor(ticker string, openPositions? Position\[\])
+  +totalMarketValueAtUnitPrice(unitPrice number): number
+  +addOpenPosition(position Position)
+  +removeOpenPosition(position Position): boolean
+}
+
+Position: {
+  shape: class
+
+  +direction: direction
+  +quantity: number
+  +unitCost: number
+  +createdAt: Date
+  +effectiveQuantity: number
+  +effectiveCost: number
+
+  +constructor(direction Direction, quantity number, unitCost number, createdAt? Date)
+  +isBuy(): boolean
+  +isSell(): boolean
+}
+
+User <-> Holding: +owns {
+  source-arrowhead: {
+    shape: diamond
+    style.filled: true
+  }
+  target-arrowhead: 0..*
+}
+
+Holding <-> Position: +owns {
+  source-arrowhead: {
+    shape: diamond
+    style.filled: true
+  }
+  target-arrowhead: 0..*
+}

docs/assets/financial-reports.d2

@@ -0,0 +1,37 @@
+# Diagram 3: Financial Reports Caching
+# Direction: right
+# Theme: neutral-gray
+
+shape: sequence_diagram
+
+# --- Actors & Systems ---
+Client
+Backend: Backend Service
+Database: Database (Cache)
+ExternalAPI: External API (yfinance)
+
+# --- Flow ---
+Client -> Backend: GET /ticker/\{ticker\}/quarterly-reports|annual-reports
+
+Backend -> ExternalAPI: Peek for latest report's end date
+ExternalAPI -> Backend: Return latest report date
+
+Backend -> Database: Query for report matching that end date
+
+alt: {
+  "Cache Hit": {
+    Database -> Backend: Return cached report data
+  }
+
+  "Cache Miss": {
+    Database -> Backend: Report not found
+
+    Backend -> ExternalAPI: Request full financial statements
+    ExternalAPI -> Backend: Return full report data
+
+    Backend -> Database: Store new report data
+    Database -> Backend: Confirm data stored
+  }
+}
+
+Backend -> Client: 200 OK (with report

docs/assets/history-data.d2

@@ -0,0 +1,28 @@
+# Direction: right
+# Theme: neutral-gray
+
+shape: sequence_diagram
+
+Client: Client
+Backend: Backend Service
+Database: Database (Cache)
+ExternalAPI: External API (yfinance)
+
+Client -> Backend: GET /ticker/\{ticker\}/history
+Backend -> Database: Query for historical data
+
+alt: {
+  "Cache Hit": {
+    Database -> Backend: Return cached data
+  }
+
+  "Cache Miss": {
+    Database -> Backend: Data not found
+    Backend -> ExternalAPI: Request historical data
+    ExternalAPI -> Backend: Return data
+    Backend -> Database: Store new data
+    Database -> Backend: Confirm data stored
+  }
+}
+
+Backend -> Client: 200 OK (with data)