How alexander-cho/tradelens works
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: Tradelens.Api API boundary · Tradelens.Core Core domain · docker-compose.yml Compose stack · Tradelens.Infrastructure Data layer
Components 22
Frontend
Angular client and shared UI code
- Client app · Feature-based Angular 20 application with route-driven screens and layout components
apps/client-ng - API services · Feature services plus auth interceptor that call the backend API
apps/client-ng/src/app/core/services - Feature screens · Auth, home, feed, companies, dashboard, chart engine, options, macro, congress, earnings, and brokerage screens
apps/client-ng/src/app/features - Layout shell · Navbar, sidebar, footer, and reusable page chrome
apps/client-ng/src/app/layout
Backend
.NET API, domain, infrastructure, and jobs
- API boundary · HTTP controllers, fallback routing, and centralized exception handling
apps/tradelens/src/Tradelens.Api - Auth API · Authentication and identity-related endpoints
apps/tradelens/src/Tradelens.Api/Controllers/AuthController.cs - Market API · Stocks, market data, bar aggregates, and fallback routing
apps/tradelens/src/Tradelens.Api/Controllers/StocksController.cs - Content API · Companies, metrics, posts, congress, macro, and options endpoints
apps/tradelens/src/Tradelens.Api/Controllers/CompaniesController.cs - Core domain · Entities, interfaces, specifications, models, and calculation services
apps/tradelens/src/Tradelens.Core - Calc engine · Domain calculations such as max pain computation
apps/tradelens/src/Tradelens.Core/Services/MaxPainCalculator.cs - Specifications · Reusable filtering and query specifications for stocks and posts
apps/tradelens/src/Tradelens.Core/Specifications - Data layer · EF Core DbContext, migrations, seed data, repositories, and cache service
apps/tradelens/src/Tradelens.Infrastructure - Provider clients · HTTP clients for Finnhub, FMP, Polygon, Tradier, and FRED
apps/tradelens/src/Tradelens.Infrastructure/Clients - Mappers · Transforms vendor DTOs into internal domain and API models
apps/tradelens/src/Tradelens.Infrastructure/Mappers - Worker lane · Scheduled or continuous jobs for database sync and refresh tasks
apps/tradelens/src/Tradelens.Worker - CLI lane · Command-line entry point for document fetching and parsing tasks
apps/tradelens/src/Tradelens.Cli
Shared
Cross-app charting package
- Charting pkg · Shared chart metadata and display mappings used across the app
packages/tradelens-charting
Platform
Containers, observability, and local runtime
- External data · Market, fundamentals, options, macro, and SEC-related upstream providers
- Postgres · Primary relational persistence for app state and seeded reference data
- Redis cache · Short-lived cached API responses and local dev cache support
- Compose stack · Dockerized API, worker, database, cache, and supporting services
docker/docker-compose.yml - Observability · Grafana, Loki, and Promtail configuration for logs and metrics
config
Connections 27
- 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