# quantisight/monorepo architecture

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

- Interactive diagram: https://gitdiagram.com/quantisight/monorepo
- Repository: https://github.com/quantisight/monorepo

## Overview

Quantisight is a personal-investor research assistant. Investors track portfolios and watchlists, inspect company and market data, screen governed metrics, follow events, and ask cited research questions; the web app serves these through API routes and server-side services backed by PostgreSQL. Separately, operators inspect ingestion health while the ingest CLI plans and runs provider jobs that populate market data. The graph preserves the documented product surfaces and major ingestion stages; some subsystem links are documented rather than verified from sampled implementation excerpts.

Main entry points: [`apps/web/app/api`](https://github.com/quantisight/monorepo/tree/dev/apps/web/app/api) (API routes), [`packages/db/src/schema`](https://github.com/quantisight/monorepo/tree/dev/packages/db/src/schema) (PostgreSQL data), [`apps/ingest/src/jobs/runner.ts`](https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/jobs/runner.ts) (Job runner), [`apps/ingest/src/jobs/handlers`](https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/jobs/handlers) (Job handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_investor["Investor experience"]
  node_web["Web surfaces"]
  node_company["Company research"]
  node_portfolio["Portfolio tracking"]
  node_watchlists["Watchlists"]
  node_screener["Metric screener"]
  node_timeline["Event timeline"]
  node_chat["Research chat"]
end

subgraph group_api["Web application"]
  node_api["API routes"]
  node_services["Server services"]
  node_pipeline_ui["Pipeline dashboard"]
  node_pipeline_service["Pipeline health<br/>[pipeline.ts]"]
end

subgraph group_data["Data platform"]
  node_database[("PostgreSQL data")]
end

subgraph group_ingestion["Ingestion pipeline"]
  node_ingest_cli["Ingest CLI<br/>[cli.ts]"]
  node_planner["Job planner<br/>[planner.ts]"]
  node_runner["Job runner<br/>[runner.ts]"]
  node_handlers["Job handlers"]
  node_loaders["Data loaders"]
  node_derive["Derived metrics"]
  node_ledger["Credit ledger<br/>[ledger.ts]"]
  node_provider["Provider interface<br/>[provider.ts]"]
  node_twelve["Twelve Data adapter"]
end

subgraph group_contracts["Shared contracts"]
  node_types["Domain contracts"]
end

node_investor(("Investor"))

node_investor -->|"uses"| node_web
node_web -->|"requests"| node_api
node_api -.->|"dispatches"| node_services
node_services -.->|"reads and writes"| node_database
node_company -->|"loads research"| node_api
node_portfolio -->|"loads analytics"| node_api
node_watchlists -->|"manages lists"| node_api
node_screener -->|"runs screens"| node_api
node_timeline -->|"loads events"| node_api
node_chat -->|"sends queries"| node_api
node_pipeline_ui -->|"checks health"| node_api
node_api -.->|"routes health"| node_pipeline_service
node_pipeline_service -->|"reads status"| node_database
node_ingest_cli -->|"runs jobs"| node_runner
node_ingest_cli -->|"plans work"| node_planner
node_planner -.->|"queues jobs"| node_database
node_runner -->|"dispatches jobs"| node_handlers
node_runner -->|"updates job state"| node_database
node_handlers -->|"loads datasets"| node_loaders
node_handlers -->|"requests market data"| node_provider
node_loaders -.->|"writes market data"| node_database
node_handlers -.->|"derives metrics"| node_derive
node_runner -->|"accounts credits"| node_ledger
node_provider -.->|"implemented by"| node_twelve
node_twelve -->|"reserves credits"| node_ledger
node_twelve -->|"records requests"| node_database
node_services -->|"uses contracts"| node_types

click node_web "https://github.com/quantisight/monorepo/tree/dev/apps/web/app/(app)"
click node_company "https://github.com/quantisight/monorepo/tree/dev/apps/web/features/company"
click node_portfolio "https://github.com/quantisight/monorepo/tree/dev/apps/web/features/portfolio"
click node_watchlists "https://github.com/quantisight/monorepo/tree/dev/apps/web/features/watchlist"
click node_screener "https://github.com/quantisight/monorepo/tree/dev/apps/web/features/screener"
click node_timeline "https://github.com/quantisight/monorepo/tree/dev/apps/web/features/timeline"
click node_chat "https://github.com/quantisight/monorepo/tree/dev/apps/web/features/chat"
click node_api "https://github.com/quantisight/monorepo/tree/dev/apps/web/app/api"
click node_services "https://github.com/quantisight/monorepo/tree/dev/apps/web/server/services"
click node_pipeline_ui "https://github.com/quantisight/monorepo/tree/dev/apps/web/features/pipeline"
click node_pipeline_service "https://github.com/quantisight/monorepo/blob/dev/apps/web/server/services/pipeline.ts"
click node_database "https://github.com/quantisight/monorepo/tree/dev/packages/db/src/schema"
click node_ingest_cli "https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/cli.ts"
click node_planner "https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/jobs/planner.ts"
click node_runner "https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/jobs/runner.ts"
click node_handlers "https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/jobs/handlers"
click node_loaders "https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/loaders"
click node_derive "https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/derive"
click node_ledger "https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/budget/ledger.ts"
click node_provider "https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/providers/provider.ts"
click node_twelve "https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/providers/twelve-data"
click node_types "https://github.com/quantisight/monorepo/tree/dev/packages/types/src"

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,node_company,node_portfolio,node_watchlists,node_screener,node_timeline,node_chat toneBlue
class node_api,node_services,node_pipeline_ui,node_pipeline_service toneAmber
class node_database toneMint
class node_ingest_cli,node_planner,node_runner,node_handlers,node_loaders,node_derive,node_ledger,node_provider,node_twelve toneRose
class node_types,node_investor toneIndigo
```

## Components

### Investor experience

- [Web surfaces](https://github.com/quantisight/monorepo/tree/dev/apps/web/app/(app)): `apps/web/app/(app)`
- [Company research](https://github.com/quantisight/monorepo/tree/dev/apps/web/features/company): `apps/web/features/company`
- [Portfolio tracking](https://github.com/quantisight/monorepo/tree/dev/apps/web/features/portfolio): `apps/web/features/portfolio`
- [Watchlists](https://github.com/quantisight/monorepo/tree/dev/apps/web/features/watchlist): `apps/web/features/watchlist`
- [Metric screener](https://github.com/quantisight/monorepo/tree/dev/apps/web/features/screener): `apps/web/features/screener`
- [Event timeline](https://github.com/quantisight/monorepo/tree/dev/apps/web/features/timeline): `apps/web/features/timeline`
- [Research chat](https://github.com/quantisight/monorepo/tree/dev/apps/web/features/chat): `apps/web/features/chat`

### Web application

- [API routes](https://github.com/quantisight/monorepo/tree/dev/apps/web/app/api): `apps/web/app/api`
- [Server services](https://github.com/quantisight/monorepo/tree/dev/apps/web/server/services): `apps/web/server/services`
- [Pipeline dashboard](https://github.com/quantisight/monorepo/tree/dev/apps/web/features/pipeline): `apps/web/features/pipeline`
- [Pipeline health](https://github.com/quantisight/monorepo/blob/dev/apps/web/server/services/pipeline.ts): `apps/web/server/services/pipeline.ts`

### Data platform

- [PostgreSQL data](https://github.com/quantisight/monorepo/tree/dev/packages/db/src/schema): `packages/db/src/schema`

### Ingestion pipeline

- [Ingest CLI](https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/cli.ts): `apps/ingest/src/cli.ts`
- [Job planner](https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/jobs/planner.ts): `apps/ingest/src/jobs/planner.ts`
- [Job runner](https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/jobs/runner.ts): `apps/ingest/src/jobs/runner.ts`
- [Job handlers](https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/jobs/handlers): `apps/ingest/src/jobs/handlers`
- [Data loaders](https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/loaders): `apps/ingest/src/loaders`
- [Derived metrics](https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/derive): `apps/ingest/src/derive`
- [Credit ledger](https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/budget/ledger.ts): `apps/ingest/src/budget/ledger.ts`
- [Provider interface](https://github.com/quantisight/monorepo/blob/dev/apps/ingest/src/providers/provider.ts): `apps/ingest/src/providers/provider.ts`
- [Twelve Data adapter](https://github.com/quantisight/monorepo/tree/dev/apps/ingest/src/providers/twelve-data): `apps/ingest/src/providers/twelve-data`

### Shared contracts

- [Domain contracts](https://github.com/quantisight/monorepo/tree/dev/packages/types/src): `packages/types/src`

### Other components

- **Investor**

## Connections

- Investor → Web surfaces: uses (evidence: `README.md`)
- Web surfaces → API routes: requests (evidence: `README.md`)
- API routes → Server services: dispatches
- Server services → PostgreSQL data: reads and writes
- Company research → API routes: loads research (evidence: `README.md`)
- Portfolio tracking → API routes: loads analytics (evidence: `README.md`)
- Watchlists → API routes: manages lists (evidence: `README.md`)
- Metric screener → API routes: runs screens (evidence: `README.md`)
- Event timeline → API routes: loads events (evidence: `README.md`)
- Research chat → API routes: sends queries (evidence: `README.md`)
- Pipeline dashboard → API routes: checks health (evidence: `README.md`)
- API routes → Pipeline health: routes health
- Pipeline health → PostgreSQL data: reads status (evidence: `apps/web/server/services/pipeline.ts`)
- Ingest CLI → Job runner: runs jobs (evidence: `apps/ingest/src/cli.ts`)
- Ingest CLI → Job planner: plans work (evidence: `apps/ingest/src/cli.ts`)
- Job planner → PostgreSQL data: queues jobs
- Job runner → Job handlers: dispatches jobs (evidence: `apps/ingest/src/jobs/handlers/index.ts`)
- Job runner → PostgreSQL data: updates job state (evidence: `apps/ingest/src/jobs/runner.ts`)
- Job handlers → Data loaders: loads datasets (evidence: `apps/ingest/src/jobs/handlers/context.ts`)
- Job handlers → Provider interface: requests market data (evidence: `apps/ingest/src/jobs/handlers/context.ts`)
- Data loaders → PostgreSQL data: writes market data
- Job handlers → Derived metrics: derives metrics
- Job runner → Credit ledger: accounts credits
- Provider interface → Twelve Data adapter: implemented by (evidence: `apps/ingest/src/providers/twelve-data/client.ts`)
- Twelve Data adapter → Credit ledger: reserves credits (evidence: `apps/ingest/src/providers/twelve-data/client.ts`)
- Twelve Data adapter → PostgreSQL data: records requests (evidence: `apps/ingest/src/providers/twelve-data/client.ts`)
- Server services → Domain contracts: uses contracts (evidence: `apps/web/server/services/pipeline.ts`)