# alexander-cho/tradelens architecture

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

- Interactive diagram: https://gitdiagram.com/alexander-cho/tradelens
- Repository: https://github.com/alexander-cho/tradelens

## Overview

1. This is a monorepo centered on a financial-market platform. The main runtime split is a .NET 10 backend plus an Angular 20 client, with shared charting code in a separate TypeScript package. The backend is further divided into API, domain/core, infrastructure, CLI, and worker processes.

2. The frontend lives under `apps/client-ng` and is a feature-based Angular app. It contains route-driven screens for auth, home, feed, companies, company dashboard, chart engine, options, macro, congress, earnings calendar, and brokerage, plus reusable layout components like navbar, sidebar, and footer.

3. The Angular client is organized around thin UI components calling feature-specific services in `src/app/core/services`. These services are the client-side boundary to the backend API and are paired with an auth interceptor, so requests can be decorated with credentials or tokens before leaving the browser.

4. A significant shared presentation layer exists in `packages/tradelens-charting`. This package holds chart metadata and display mappings used across the app, which suggests charting rules and naming are intentionally shared rather than duplicated inside individual Angular features.

5. The backend API project `Tradelens.Api` is the HTTP boundary. It exposes controllers for auth, stocks, companies, company metrics, market data, options, macro, congress, posts, and bar aggregates, with a fallback controller and centralized exception handling. `BaseApiController` indicates a shared controller pattern, and `RequestHelpers` includes cache and invalidation attributes around endpoint behavior.

6. Business rules are separated into `Tradelens.Core`. This layer defines entities, domain interfaces, specifications, models, and calculation services such as `MaxPainCalculator`. It is where repository abstractions and query filters live, keeping domain logic independent from HTTP, EF Core, or third-party APIs.

7. `Tradelens.Infrastructure` implements the concrete data and integration concerns. It contains EF Core `DbContext`, migrations, repository implementations, caching, and service implementations, plus HTTP clients for external providers: Finnhub, Financial Modeling Prep, Polygon, Tradier, and FRED. This is the main adapter layer between the core domain and outside systems.

8. External data ingestion is a core architectural concern. The infrastructure clients fetch market, fundamentals, options, macro, and SEC-related data, then mapper classes convert provider DTOs into internal models. That mapping boundary is important because the app normalizes several vendor schemas into one internal shape for the UI and domain.

9. Persistence is Postgres-backed, with EF Core migrations and seed data stored inside the infrastructure project. The repo also includes a Redis dev container and a response cache service, so both durable state and short-lived cached API responses are part of the design. Seed files include tickers, posts, and historical company fundamentals, indicating the app can bootstrap itself with offline/reference data.

10. Authentication and user data are first-class backend concerns. The API has auth controllers and identity-related extensions, while the frontend includes landing/login/register flows. The architecture implies token-based authenticated requests from the Angular client to protected API endpoints.

11. There is an explicit background-processing lane in `Tradelens.Worker`. The worker hosts scheduled or continuous jobs such as database sync, which keeps slow or periodic data refreshes out of the request/response path. That separation is important for the diagram: user-facing API traffic and background refresh traffic are distinct flows.

12. The CLI project (`Tradelens.Cli`) is another non-UI entry point used for orchestration tasks such as document fetching/parsing. It reuses the same core and infrastructure services, which means it participates in the same business and data boundaries without going through the HTTP API.

13. Cross-cutting platform concerns are handled with Docker, compose files, and observability config. The repo includes container definitions for API, worker, Postgres, Redis, and supporting tooling, plus Grafana/Loki/Promtail configuration, indicating the application is intended to run as a composed local or deployed service stack with centralized logs and metrics.

14. The main data flow is: UI component → Angular service → authenticated HTTP request → API controller → core service/repository/specification → infrastructure adapter or database/cache → mapped response back to the UI. For background refresh, the worker and CLI feed the same infrastructure/domain layers, which then update the database or cached state used by the API and client.

Main entry points: [`apps/tradelens/src/Tradelens.Api`](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api) (API boundary), [`apps/tradelens/src/Tradelens.Core`](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Core) (Core domain), [`docker/docker-compose.yml`](https://github.com/alexander-cho/tradelens/blob/dev/docker/docker-compose.yml) (Compose stack), [`apps/tradelens/src/Tradelens.Infrastructure`](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Infrastructure) (Data layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_client_app["Client app<br/>Angular UI"]
  node_client_services["API services<br/>Client boundary"]
  node_client_features["Feature screens<br/>UI features"]
  node_client_layout["Layout shell<br/>UI shell"]
end

subgraph group_backend["Backend"]
  node_api_boundary["API boundary<br/>ASP.NET API<br/>[Tradelens.Api]"]
  node_api_auth["Auth API<br/>Controller set<br/>[AuthController.cs]"]
  node_api_market["Market API<br/>Controller set"]
  node_api_content["Content API<br/>Controller set"]
  node_core_domain["Core domain<br/>Domain layer<br/>[Tradelens.Core]"]
  node_core_calc(("Calc engine<br/>Domain service"))
  node_core_specs["Specifications<br/>Query rules<br/>[Specifications]"]
  node_infra_data[("Data layer<br/>Persistence")]
  node_infra_clients["Provider clients<br/>Integrations<br/>[Clients]"]
  node_infra_mappers["Mappers<br/>Normalization<br/>[Mappers]"]
  node_worker_lane["Worker lane<br/>Background jobs<br/>[Tradelens.Worker]"]
  node_cli_lane["CLI lane<br/>Orchestration<br/>[Tradelens.Cli]"]
end

subgraph group_shared["Shared"]
  node_charting_pkg["Charting pkg<br/>Shared TS"]
end

subgraph group_platform["Platform"]
  node_external_sources(("External data<br/>Vendor APIs"))
  node_postgres_store[("Postgres<br/>Database")]
  node_redis_cache[("Redis cache")]
  node_compose_stack{{"Compose stack<br/>Runtime<br/>[docker-compose.yml]"}}
  node_observability["Observability<br/>Logging stack"]
end

node_client_app -->|"renders"| node_client_features
node_client_app -->|"uses"| node_client_layout
node_client_features -->|"calls"| node_client_services
node_client_services -->|"HTTP"| node_api_boundary
node_client_services -->|"shares rules"| node_charting_pkg
node_api_boundary -->|"hosts"| node_api_auth
node_api_boundary -->|"hosts"| node_api_market
node_api_boundary -->|"hosts"| node_api_content
node_api_boundary -->|"depends on"| node_core_domain
node_api_boundary -->|"uses"| node_infra_data
node_core_domain -->|"contains"| node_core_calc
node_core_domain -->|"contains"| node_core_specs
node_infra_data -->|"persists"| node_postgres_store
node_infra_data -->|"caches"| node_redis_cache
node_infra_data -->|"adapts"| node_infra_clients
node_infra_clients -->|"fetches from"| node_external_sources
node_infra_clients -->|"normalizes"| node_infra_mappers
node_infra_mappers -->|"feeds models"| node_core_domain
node_worker_lane -->|"syncs"| node_infra_data
node_worker_lane -->|"reuses"| node_core_domain
node_cli_lane -->|"imports data"| node_infra_clients
node_cli_lane -->|"reuses"| node_core_domain
node_compose_stack -->|"starts"| node_api_boundary
node_compose_stack -->|"starts"| node_worker_lane
node_compose_stack -->|"provisions"| node_postgres_store
node_compose_stack -->|"provisions"| node_redis_cache
node_observability -->|"monitors"| node_compose_stack

click node_client_app "https://github.com/alexander-cho/tradelens/tree/dev/apps/client-ng"
click node_client_services "https://github.com/alexander-cho/tradelens/tree/dev/apps/client-ng/src/app/core/services"
click node_client_features "https://github.com/alexander-cho/tradelens/tree/dev/apps/client-ng/src/app/features"
click node_client_layout "https://github.com/alexander-cho/tradelens/tree/dev/apps/client-ng/src/app/layout"
click node_charting_pkg "https://github.com/alexander-cho/tradelens/tree/dev/packages/tradelens-charting"
click node_api_boundary "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api"
click node_api_auth "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api/Controllers/AuthController.cs"
click node_api_market "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api/Controllers/StocksController.cs"
click node_api_content "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api/Controllers/CompaniesController.cs"
click node_core_domain "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Core"
click node_core_calc "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Core/Services/MaxPainCalculator.cs"
click node_core_specs "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Core/Specifications"
click node_infra_data "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Infrastructure"
click node_infra_clients "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Infrastructure/Clients"
click node_infra_mappers "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Infrastructure/Mappers"
click node_worker_lane "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Worker"
click node_cli_lane "https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Cli"
click node_compose_stack "https://github.com/alexander-cho/tradelens/blob/dev/docker/docker-compose.yml"
click node_observability "https://github.com/alexander-cho/tradelens/tree/dev/config"

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_client_app,node_client_services,node_client_features,node_client_layout toneBlue
class node_api_boundary,node_api_auth,node_api_market,node_api_content,node_core_domain,node_core_calc,node_core_specs,node_infra_data,node_infra_clients,node_infra_mappers,node_worker_lane,node_cli_lane toneAmber
class node_charting_pkg toneMint
class node_external_sources,node_postgres_store,node_redis_cache,node_compose_stack,node_observability toneRose
```

## Components

### Frontend

Angular client and shared UI code

- [Client app](https://github.com/alexander-cho/tradelens/tree/dev/apps/client-ng): Angular UI · Feature-based Angular 20 application with route-driven screens and layout components · `apps/client-ng`
- [API services](https://github.com/alexander-cho/tradelens/tree/dev/apps/client-ng/src/app/core/services): Client boundary · Feature services plus auth interceptor that call the backend API · `apps/client-ng/src/app/core/services`
- [Feature screens](https://github.com/alexander-cho/tradelens/tree/dev/apps/client-ng/src/app/features): UI features · Auth, home, feed, companies, dashboard, chart engine, options, macro, congress, earnings, and brokerage screens · `apps/client-ng/src/app/features`
- [Layout shell](https://github.com/alexander-cho/tradelens/tree/dev/apps/client-ng/src/app/layout): UI shell · Navbar, sidebar, footer, and reusable page chrome · `apps/client-ng/src/app/layout`

### Backend

.NET API, domain, infrastructure, and jobs

- [API boundary](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api): ASP.NET API · HTTP controllers, fallback routing, and centralized exception handling · `apps/tradelens/src/Tradelens.Api`
- [Auth API](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api/Controllers/AuthController.cs): Controller set · Authentication and identity-related endpoints · `apps/tradelens/src/Tradelens.Api/Controllers/AuthController.cs`
- [Market API](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api/Controllers/StocksController.cs): Controller set · Stocks, market data, bar aggregates, and fallback routing · `apps/tradelens/src/Tradelens.Api/Controllers/StocksController.cs`
- [Content API](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Api/Controllers/CompaniesController.cs): Controller set · Companies, metrics, posts, congress, macro, and options endpoints · `apps/tradelens/src/Tradelens.Api/Controllers/CompaniesController.cs`
- [Core domain](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Core): Domain layer · Entities, interfaces, specifications, models, and calculation services · `apps/tradelens/src/Tradelens.Core`
- [Calc engine](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Core/Services/MaxPainCalculator.cs): Domain service · Domain calculations such as max pain computation · `apps/tradelens/src/Tradelens.Core/Services/MaxPainCalculator.cs`
- [Specifications](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Core/Specifications): Query rules · Reusable filtering and query specifications for stocks and posts · `apps/tradelens/src/Tradelens.Core/Specifications`
- [Data layer](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Infrastructure): Persistence · EF Core DbContext, migrations, seed data, repositories, and cache service · `apps/tradelens/src/Tradelens.Infrastructure`
- [Provider clients](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Infrastructure/Clients): Integrations · HTTP clients for Finnhub, FMP, Polygon, Tradier, and FRED · `apps/tradelens/src/Tradelens.Infrastructure/Clients`
- [Mappers](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Infrastructure/Mappers): Normalization · Transforms vendor DTOs into internal domain and API models · `apps/tradelens/src/Tradelens.Infrastructure/Mappers`
- [Worker lane](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Worker): Background jobs · Scheduled or continuous jobs for database sync and refresh tasks · `apps/tradelens/src/Tradelens.Worker`
- [CLI lane](https://github.com/alexander-cho/tradelens/blob/dev/apps/tradelens/src/Tradelens.Cli): Orchestration · Command-line entry point for document fetching and parsing tasks · `apps/tradelens/src/Tradelens.Cli`

### Shared

Cross-app charting package

- [Charting pkg](https://github.com/alexander-cho/tradelens/tree/dev/packages/tradelens-charting): Shared TS · Shared chart metadata and display mappings used across the app · `packages/tradelens-charting`

### Platform

Containers, observability, and local runtime

- **External data**: Vendor APIs · Market, fundamentals, options, macro, and SEC-related upstream providers
- **Postgres**: Database · Primary relational persistence for app state and seeded reference data
- **Redis cache**: Cache · Short-lived cached API responses and local dev cache support
- [Compose stack](https://github.com/alexander-cho/tradelens/blob/dev/docker/docker-compose.yml): Runtime · Dockerized API, worker, database, cache, and supporting services · `docker/docker-compose.yml`
- [Observability](https://github.com/alexander-cho/tradelens/tree/dev/config): Logging stack · Grafana, Loki, and Promtail configuration for logs and metrics · `config`

## Connections

- Client app → Feature screens: renders · Route-driven screens are assembled inside the Angular app
- Client app → Layout shell: uses · Global layout and navigation shell wrap the screens
- Feature screens → API services: calls · Feature components delegate data access to thin client services
- API services → API boundary: HTTP · Authenticated requests leave the browser through the API boundary
- API services → Charting pkg: shares rules · Client chart screens reuse shared chart metadata and mappings
- API boundary → Auth API: hosts · Authentication endpoints are exposed through the API layer
- API boundary → Market API: hosts · Market and stock endpoints are exposed through the API layer
- API boundary → Content API: hosts · Content and analytics endpoints are exposed through the API layer
- API boundary → Core domain: depends on · Controllers defer business rules to the core domain
- API boundary → Data layer: uses · API wiring registers repositories, caching, and persistence services
- Core domain → Calc engine: contains · Domain calculations live inside the core layer
- Core domain → Specifications: contains · Query filters and repository rules are centralized as specifications
- Data layer → Postgres: persists · EF Core stores application state in Postgres
- Data layer → Redis cache: caches · Response caching supports API read paths
- Data layer → Provider clients: adapts · Infrastructure consumes vendor integrations through typed clients
- Provider clients → External data: fetches from · Upstream providers supply market, fundamentals, options, and macro data
- Provider clients → Mappers: normalizes · Provider DTOs are mapped into internal models
- Mappers → Core domain: feeds models · Mapped data is shaped for domain and API consumption
- Worker lane → Data layer: syncs · Background refresh jobs update persisted data
- Worker lane → Core domain: reuses · Jobs share the same core services and rules as the API
- CLI lane → Provider clients: imports data · CLI tasks reuse provider integrations for document and data fetching
- CLI lane → Core domain: reuses · Command-line orchestration runs through shared domain logic
- Compose stack → API boundary: starts · Docker compose runs the API service
- Compose stack → Worker lane: starts · Docker compose runs the worker service
- Compose stack → Postgres: provisions · Compose includes the database service
- Compose stack → Redis cache: provisions · Compose includes the cache service
- Observability → Compose stack: monitors · Logging stack observes the composed runtime
