# jorgeofthejungle/pse-quant-saas architecture

> Architecture diagram of the GitHub repository jorgeofthejungle/pse-quant-saas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jorgeofthejungle/pse-quant-saas
- Repository: https://github.com/jorgeofthejungle/pse-quant-saas

## Overview

StockPilot PH is a Philippine-equities research SaaS. Investors use the Next.js screens to request rankings, stock research, watchlists, and live updates; the FastAPI gateway serves those requests using quantitative engines and persistent data. The README also documents ingestion, reports, payments, search, task workers, telemetry, caching, and disaster recovery. The repository contains a substantial legacy pipeline alongside the v2 backend; its principal scoring and valuation components are represented, but sampled evidence does not establish all legacy runtime links. Unsampled subsystem paths are based on the tree and documented capabilities.

Main entry points: [`backend/pse_quant/api/routes`](https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/backend/pse_quant/api/routes) (API routes), [`backend/pse_quant/db/models.py`](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/db/models.py) (Research database), [`backend/pse_quant/api/main.py`](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/api/main.py) (FastAPI gateway), [`frontend/src/app`](https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/frontend/src/app) (Research web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Investor presentation"]
  node_web_app["Research web app"]
  node_web_api["Frontend API adapters<br/>[api.ts]"]
end

subgraph group_ingress["API and services"]
  node_gateway["FastAPI gateway<br/>[main.py]"]
  node_routes["API routes"]
  node_auth["Identity and customers<br/>[auth_service.py]"]
  node_payments["Payments and webhooks<br/>[payments.py]"]
end

subgraph group_research["Research engines"]
  node_scoring["Fundamental scoring<br/>[scoring.py]"]
  node_valuation["Valuation and MoS<br/>[mos.py]"]
  node_oaas["OaaS analysis<br/>[oaas_engine.py]"]
  node_scraping["Market data ingestion"]
  node_search["Equity full-text search<br/>[fts_engine.py]"]
  node_legacy_pipeline["Legacy research pipeline<br/>[main.py]"]
  node_legacy_scorer["Legacy scoring<br/>[scorer_v2.py]"]
  node_legacy_valuation["Legacy MoS<br/>[mos.py]"]
end

subgraph group_runtime["Workers and integrations"]
  node_reports["Research reports<br/>[generator.py]"]
  node_tasks["Leased task workers<br/>[engine.py]"]
  node_streaming["SSE stream hub<br/>[hub.py]"]
  node_telemetry["Tracing and telemetry"]
end

subgraph group_persistence["Data and recovery"]
  node_database[("Research database<br/>[models.py]")]
  node_cache[("Cache engine<br/>[engine.py]")]
  node_snapshots["Backup and snapshots<br/>[snapshot_engine.py]"]
end

node_investor(("Investor"))
node_pse(("PSE data sources"))
node_payment_provider(("Payment provider"))

node_investor -->|"uses"| node_web_app
node_web_app -->|"requests data"| node_web_api
node_web_api -->|"HTTP JSON / SSE"| node_gateway
node_gateway -->|"registers"| node_routes
node_gateway -->|"routes persistence"| node_database
node_gateway -->|"traces requests"| node_telemetry
node_routes -.->|"serves identity"| node_auth
node_routes -.->|"handles payment requests"| node_payments
node_payment_provider -->|"sends webhooks"| node_payments
node_routes -.->|"requests rankings"| node_scoring
node_routes -.->|"requests valuation"| node_valuation
node_routes -.->|"requests analysis"| node_oaas
node_routes -.->|"queries"| node_search
node_pse -.->|"provides market data"| node_scraping
node_scraping -.->|"stores market data"| node_database
node_database -->|"indexes equities"| node_search
node_legacy_pipeline -->|"scores stocks"| node_legacy_scorer
node_legacy_pipeline -->|"enriches MoS"| node_legacy_valuation
node_tasks -->|"leases task records"| node_database
node_tasks -->|"uses task stream"| node_streaming
node_reports -.->|"reads research data"| node_database
node_database -->|"backs up"| node_snapshots
node_gateway -.->|"uses cache"| node_cache
node_web_app -->|"subscribes to updates"| node_streaming

click node_web_app "https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/frontend/src/app"
click node_web_api "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/frontend/src/lib/api.ts"
click node_gateway "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/api/main.py"
click node_routes "https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/backend/pse_quant/api/routes"
click node_auth "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/services/auth_service.py"
click node_payments "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/api/routes/payments.py"
click node_scoring "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/core/scoring.py"
click node_valuation "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/core/mos.py"
click node_oaas "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/core/oaas_engine.py"
click node_scraping "https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/backend/pse_quant/scraper"
click node_search "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/search/fts_engine.py"
click node_legacy_pipeline "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/legacy/main.py"
click node_legacy_scorer "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/legacy/engine/scorer_v2.py"
click node_legacy_valuation "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/legacy/engine/mos.py"
click node_reports "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/reporting/generator.py"
click node_tasks "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/tasks/engine.py"
click node_streaming "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/streaming/hub.py"
click node_telemetry "https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/backend/pse_quant/telemetry"
click node_database "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/db/models.py"
click node_cache "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/cache/engine.py"
click node_snapshots "https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/backup/snapshot_engine.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_app,node_web_api toneBlue
class node_gateway,node_routes,node_auth,node_payments toneAmber
class node_scoring,node_valuation,node_oaas,node_scraping,node_search,node_legacy_pipeline,node_legacy_scorer,node_legacy_valuation toneMint
class node_reports,node_tasks,node_streaming,node_telemetry toneRose
class node_database,node_cache,node_snapshots,node_investor,node_pse,node_payment_provider toneIndigo
```

## Components

### Investor presentation

- [Research web app](https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/frontend/src/app): `frontend/src/app`
- [Frontend API adapters](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and services

- [FastAPI gateway](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/api/main.py): `backend/pse_quant/api/main.py`
- [API routes](https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/backend/pse_quant/api/routes): `backend/pse_quant/api/routes`
- [Identity and customers](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/services/auth_service.py): `backend/pse_quant/services/auth_service.py`
- [Payments and webhooks](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/api/routes/payments.py): `backend/pse_quant/api/routes/payments.py`

### Research engines

- [Fundamental scoring](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/core/scoring.py): `backend/pse_quant/core/scoring.py`
- [Valuation and MoS](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/core/mos.py): `backend/pse_quant/core/mos.py`
- [OaaS analysis](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/core/oaas_engine.py): `backend/pse_quant/core/oaas_engine.py`
- [Market data ingestion](https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/backend/pse_quant/scraper): `backend/pse_quant/scraper`
- [Equity full-text search](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/search/fts_engine.py): `backend/pse_quant/search/fts_engine.py`
- [Legacy research pipeline](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/legacy/main.py): `legacy/main.py`
- [Legacy scoring](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/legacy/engine/scorer_v2.py): `legacy/engine/scorer_v2.py`
- [Legacy MoS](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/legacy/engine/mos.py): `legacy/engine/mos.py`

### Workers and integrations

- [Research reports](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/reporting/generator.py): `backend/pse_quant/reporting/generator.py`
- [Leased task workers](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/tasks/engine.py): `backend/pse_quant/tasks/engine.py`
- [SSE stream hub](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/streaming/hub.py): `backend/pse_quant/streaming/hub.py`
- [Tracing and telemetry](https://github.com/jorgeofthejungle/pse-quant-saas/tree/main/backend/pse_quant/telemetry): `backend/pse_quant/telemetry`

### Data and recovery

- [Research database](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/db/models.py): `backend/pse_quant/db/models.py`
- [Cache engine](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/cache/engine.py): `backend/pse_quant/cache/engine.py`
- [Backup and snapshots](https://github.com/jorgeofthejungle/pse-quant-saas/blob/main/backend/pse_quant/backup/snapshot_engine.py): `backend/pse_quant/backup/snapshot_engine.py`

### Other components

- **Investor**
- **PSE data sources**
- **Payment provider**

## Connections

- Investor → Research web app: uses
- Research web app → Frontend API adapters: requests data
- Frontend API adapters → FastAPI gateway: HTTP JSON / SSE
- FastAPI gateway → API routes: registers (evidence: `backend/pse_quant/api/main.py`)
- FastAPI gateway → Research database: routes persistence
- FastAPI gateway → Tracing and telemetry: traces requests (evidence: `backend/pse_quant/api/main.py`)
- API routes → Identity and customers: serves identity
- API routes → Payments and webhooks: handles payment requests
- Payment provider → Payments and webhooks: sends webhooks
- API routes → Fundamental scoring: requests rankings
- API routes → Valuation and MoS: requests valuation
- API routes → OaaS analysis: requests analysis
- API routes → Equity full-text search: queries
- PSE data sources → Market data ingestion: provides market data
- Market data ingestion → Research database: stores market data
- Research database → Equity full-text search: indexes equities (evidence: `backend/pse_quant/search/fts_engine.py`)
- Legacy research pipeline → Legacy scoring: scores stocks (evidence: `legacy/main.py`)
- Legacy research pipeline → Legacy MoS: enriches MoS (evidence: `legacy/main.py`)
- Leased task workers → Research database: leases task records (evidence: `backend/pse_quant/tasks/engine.py`)
- Leased task workers → SSE stream hub: uses task stream (evidence: `backend/pse_quant/tasks/engine.py`)
- Research reports → Research database: reads research data
- Research database → Backup and snapshots: backs up (evidence: `backend/pse_quant/backup/snapshot_engine.py`)
- FastAPI gateway → Cache engine: uses cache
- Research web app → SSE stream hub: subscribes to updates