# namiujrm/ontrade architecture

> Architecture diagram of the GitHub repository namiujrm/ontrade, 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/namiujrm/ontrade
- Repository: https://github.com/namiujrm/ontrade

## Overview

Ontrade is a Vietnamese-market data ingestion and personal investment advisory platform. Its principal flow collects and normalizes market, financial, and corporate-action data, persists it, then serves market/fundamental queries and portfolio or statement analysis through the API. A separate quant pipeline encodes financial features into embeddings for similarity search; realtime snapshots and broker-statement reconciliation are additional product branches. Relationships for unsampled API and similarity capabilities follow README descriptions; source excerpts do not expose all runtime wiring.

Main entry points: [`src/ontrade/infrastructure/database/repositories`](https://github.com/namiujrm/ontrade/tree/main/src/ontrade/infrastructure/database/repositories) (Data repositories), [`src/ontrade/api/v1/user`](https://github.com/namiujrm/ontrade/tree/main/src/ontrade/api/v1/user) (User routes), [`src/ontrade/api/main.py`](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/api/main.py) (REST API), [`src/ontrade/services/system/vector_pipeline_service.py`](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/system/vector_pipeline_service.py) (Vector pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["API and access"]
  node_api["REST API<br/>[main.py]"]
  node_user_routes["User routes"]
  node_admin_routes["Admin routes"]
end

subgraph group_ingestion["Data collection"]
  node_market_ingestion["Market ingestion"]
  node_market_crawlers["Historical crawlers"]
  node_financial_ingestion["Financial ingestion"]
  node_financial_crawlers["Financial crawlers"]
  node_corporate_actions["Corporate actions"]
end

subgraph group_domain["Investment services"]
  node_statement_service["Statement processing"]
  node_reconcile["Order reconciliation"]
  node_market_query["Market queries"]
  node_portfolio["Portfolio and behavior"]
  node_behavior_audit["Behavioral audit"]
  node_realtime["Realtime market service"]
  node_similarity["Similarity search"]
end

subgraph group_platform["Persistence and analytics"]
  node_repositories["Data repositories"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_realtime_cache["Realtime cache<br/>[realtime_cache.py]"]
  node_vector_pipeline["Vector pipeline"]
  node_feature_encoder["Feature encoder<br/>[feature_encoder.py]"]
  node_embeddings[("Embedding store<br/>[vector_repo.py]")]
end

node_investor(("Investor"))
node_operator(("Operator"))
node_market_sources(("Market sources"))
node_broker_files["Broker statements"]
node_postgres[("PostgreSQL / TimescaleDB")]
node_redis[("Redis")]

node_investor -->|"requests"| node_api
node_operator -->|"administers"| node_api
node_api -->|"routes"| node_user_routes
node_api -->|"routes"| node_admin_routes
node_operator -->|"triggers"| node_market_ingestion
node_market_ingestion -->|"fetches prices"| node_market_crawlers
node_market_sources -->|"provides data"| node_market_crawlers
node_market_ingestion -->|"writes quotes"| node_repositories
node_operator -->|"triggers"| node_financial_ingestion
node_financial_ingestion -->|"fetches statements"| node_financial_crawlers
node_financial_ingestion -->|"stores statements"| node_repositories
node_operator -->|"triggers"| node_corporate_actions
node_corporate_actions -->|"stores actions"| node_repositories
node_broker_files -->|"uploads"| node_statement_service
node_statement_service -->|"reconciles orders"| node_reconcile
node_reconcile -->|"reads and writes"| node_repositories
node_user_routes -.->|"serves queries"| node_market_query
node_market_query -->|"reads market data"| node_repositories
node_user_routes -.->|"serves portfolios"| node_portfolio
node_user_routes -.->|"serves statements"| node_statement_service
node_behavior_audit -->|"reads orders"| node_repositories
node_user_routes -.->|"offers coaching"| node_behavior_audit
node_db_session -->|"connects"| node_postgres
node_repositories -.->|"reads and writes"| node_postgres
node_realtime -->|"updates snapshots"| node_realtime_cache
node_realtime_cache -.->|"caches"| node_redis
node_market_sources -.->|"supplies quotes"| node_realtime
node_vector_pipeline -->|"reads ratios and symbols"| node_repositories
node_vector_pipeline -->|"encodes features"| node_feature_encoder
node_vector_pipeline -->|"upserts vectors"| node_embeddings
node_user_routes -.->|"offers similarity"| node_similarity
node_similarity -.->|"searches vectors"| node_embeddings

click node_api "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/api/main.py"
click node_user_routes "https://github.com/namiujrm/ontrade/tree/main/src/ontrade/api/v1/user"
click node_admin_routes "https://github.com/namiujrm/ontrade/tree/main/src/ontrade/api/v1/admin"
click node_market_ingestion "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/admin/market_ingestion_service.py"
click node_market_crawlers "https://github.com/namiujrm/ontrade/tree/main/src/ontrade/crawlers/historical_price"
click node_financial_ingestion "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/admin/financial_ingestion_service.py"
click node_financial_crawlers "https://github.com/namiujrm/ontrade/tree/main/src/ontrade/crawlers/financial_statement"
click node_corporate_actions "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/admin/corporate_action_service.py"
click node_statement_service "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/statement_service.py"
click node_reconcile "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/statement_reconcile_service.py"
click node_market_query "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/market_query_service.py"
click node_portfolio "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/portfolio_service.py"
click node_behavior_audit "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/behavioral_audit_service.py"
click node_repositories "https://github.com/namiujrm/ontrade/tree/main/src/ontrade/infrastructure/database/repositories"
click node_db_session "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/infrastructure/database/session.py"
click node_realtime "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/system/realtime_market_service.py"
click node_realtime_cache "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/infrastructure/cache/realtime_cache.py"
click node_vector_pipeline "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/system/vector_pipeline_service.py"
click node_feature_encoder "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/analytics/feature_encoder.py"
click node_similarity "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/hnsw_similarity_service.py"
click node_embeddings "https://github.com/namiujrm/ontrade/blob/main/src/ontrade/infrastructure/database/repositories/vector_repo.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_api,node_user_routes,node_admin_routes toneBlue
class node_market_ingestion,node_market_crawlers,node_financial_ingestion,node_financial_crawlers,node_corporate_actions,node_postgres,node_redis toneAmber
class node_statement_service,node_reconcile,node_market_query,node_portfolio,node_behavior_audit,node_realtime,node_similarity toneMint
class node_repositories,node_db_session,node_realtime_cache,node_vector_pipeline,node_feature_encoder,node_embeddings toneRose
class node_investor,node_operator,node_market_sources,node_broker_files toneIndigo
```

## Components

### API and access

- [REST API](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/api/main.py): `src/ontrade/api/main.py`
- [User routes](https://github.com/namiujrm/ontrade/tree/main/src/ontrade/api/v1/user): `src/ontrade/api/v1/user`
- [Admin routes](https://github.com/namiujrm/ontrade/tree/main/src/ontrade/api/v1/admin): `src/ontrade/api/v1/admin`

### Data collection

- [Market ingestion](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/admin/market_ingestion_service.py): `src/ontrade/services/admin/market_ingestion_service.py`
- [Historical crawlers](https://github.com/namiujrm/ontrade/tree/main/src/ontrade/crawlers/historical_price): `src/ontrade/crawlers/historical_price`
- [Financial ingestion](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/admin/financial_ingestion_service.py): `src/ontrade/services/admin/financial_ingestion_service.py`
- [Financial crawlers](https://github.com/namiujrm/ontrade/tree/main/src/ontrade/crawlers/financial_statement): `src/ontrade/crawlers/financial_statement`
- [Corporate actions](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/admin/corporate_action_service.py): `src/ontrade/services/admin/corporate_action_service.py`

### Investment services

- [Statement processing](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/statement_service.py): `src/ontrade/services/user/statement_service.py`
- [Order reconciliation](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/statement_reconcile_service.py): `src/ontrade/services/user/statement_reconcile_service.py`
- [Market queries](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/market_query_service.py): `src/ontrade/services/user/market_query_service.py`
- [Portfolio and behavior](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/portfolio_service.py): `src/ontrade/services/user/portfolio_service.py`
- [Behavioral audit](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/behavioral_audit_service.py): `src/ontrade/services/user/behavioral_audit_service.py`
- [Realtime market service](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/system/realtime_market_service.py): `src/ontrade/services/system/realtime_market_service.py`
- [Similarity search](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/user/hnsw_similarity_service.py): `src/ontrade/services/user/hnsw_similarity_service.py`

### Persistence and analytics

- [Data repositories](https://github.com/namiujrm/ontrade/tree/main/src/ontrade/infrastructure/database/repositories): `src/ontrade/infrastructure/database/repositories`
- [Database sessions](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/infrastructure/database/session.py): `src/ontrade/infrastructure/database/session.py`
- [Realtime cache](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/infrastructure/cache/realtime_cache.py): `src/ontrade/infrastructure/cache/realtime_cache.py`
- [Vector pipeline](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/services/system/vector_pipeline_service.py): `src/ontrade/services/system/vector_pipeline_service.py`
- [Feature encoder](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/analytics/feature_encoder.py): `src/ontrade/analytics/feature_encoder.py`
- [Embedding store](https://github.com/namiujrm/ontrade/blob/main/src/ontrade/infrastructure/database/repositories/vector_repo.py): `src/ontrade/infrastructure/database/repositories/vector_repo.py`

### Other components

- **Investor**
- **Operator**
- **Market sources**
- **Broker statements**
- **PostgreSQL / TimescaleDB**
- **Redis**

## Connections

- Investor → REST API: requests (evidence: `README.md`)
- Operator → REST API: administers (evidence: `README.md`)
- REST API → User routes: routes
- REST API → Admin routes: routes
- Operator → Market ingestion: triggers (evidence: `README.md`)
- Market ingestion → Historical crawlers: fetches prices (evidence: `src/ontrade/services/admin/market_ingestion_service.py`)
- Market sources → Historical crawlers: provides data (evidence: `README.md`)
- Market ingestion → Data repositories: writes quotes (evidence: `src/ontrade/services/admin/market_ingestion_service.py`)
- Operator → Financial ingestion: triggers (evidence: `README.md`)
- Financial ingestion → Financial crawlers: fetches statements (evidence: `src/ontrade/services/admin/financial_ingestion_service.py`)
- Financial ingestion → Data repositories: stores statements (evidence: `src/ontrade/services/admin/financial_ingestion_service.py`)
- Operator → Corporate actions: triggers (evidence: `README.md`)
- Corporate actions → Data repositories: stores actions (evidence: `src/ontrade/services/admin/corporate_action_service.py`)
- Broker statements → Statement processing: uploads (evidence: `README.md`)
- Statement processing → Order reconciliation: reconciles orders (evidence: `src/ontrade/services/user/statement_reconcile_service.py`)
- Order reconciliation → Data repositories: reads and writes (evidence: `src/ontrade/services/user/statement_reconcile_service.py`)
- User routes → Market queries: serves queries
- Market queries → Data repositories: reads market data (evidence: `src/ontrade/services/user/market_query_service.py`)
- User routes → Portfolio and behavior: serves portfolios
- User routes → Statement processing: serves statements
- Behavioral audit → Data repositories: reads orders (evidence: `src/ontrade/services/user/behavioral_audit_service.py`)
- User routes → Behavioral audit: offers coaching
- Database sessions → PostgreSQL / TimescaleDB: connects (evidence: `src/ontrade/infrastructure/database/session.py`)
- Data repositories → PostgreSQL / TimescaleDB: reads and writes
- Realtime market service → Realtime cache: updates snapshots (evidence: `src/ontrade/services/system/realtime_market_service.py`)
- Realtime cache → Redis: caches
- Market sources → Realtime market service: supplies quotes
- Vector pipeline → Data repositories: reads ratios and symbols (evidence: `src/ontrade/services/system/vector_pipeline_service.py`)
- Vector pipeline → Feature encoder: encodes features (evidence: `src/ontrade/services/system/vector_pipeline_service.py`)
- Vector pipeline → Embedding store: upserts vectors (evidence: `src/ontrade/services/system/vector_pipeline_service.py`)
- User routes → Similarity search: offers similarity
- Similarity search → Embedding store: searches vectors (evidence: `README.md`)