# adrian-hue-pixel/trendtrace architecture

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

- Interactive diagram: https://gitdiagram.com/adrian-hue-pixel/trendtrace
- Repository: https://github.com/adrian-hue-pixel/trendtrace

## Overview

TrendTrace is a FastAPI backend for exploring rainfall and aerosol data, exporting CSV, and producing downloadable PDF Discovery Reports. The main workflow is a client request routed through the API to validated analysis backed by a selected data store; report requests assemble those results and render a PDF. The README documents additional analysis capabilities whose routes are not fully represented in the excerpts. Edges below rely on README statements, visible application wiring, and SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`backend/app/main.py`](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/main.py) (App bootstrap), [`backend/app/routers/reports.py`](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/reports.py) (Report endpoints), [`backend/app/services/store.py`](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/store.py) (Data store), [`backend/app/services/csv_export.py`](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/csv_export.py) (CSV builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and contracts"]
  node_app["App bootstrap<br/>[main.py]"]
  node_schemas["Core schemas<br/>[schemas.py]"]
  node_advanced_schemas["Advanced schemas"]
  node_health["Health endpoint<br/>[health.py]"]
  node_metadata["Metadata endpoints<br/>[metadata.py]"]
  node_analysis_routes["Analysis endpoints<br/>[advanced.py]"]
  node_common["Response envelopes<br/>[common.py]"]
end

subgraph group_data["Data and analysis"]
  node_store[("Data store<br/>[store.py]")]
  node_validation["Request validation<br/>[validation.py]"]
  node_analysis["Analysis services<br/>[advanced.py]"]
  node_mock_data[("Mock datasets")]
end

subgraph group_exports["Exports and reports"]
  node_csv_route["CSV endpoint<br/>[export.py]"]
  node_csv_export["CSV builder<br/>[csv_export.py]"]
  node_csv_codec["CSV codec<br/>[csv_codec.py]"]
  node_report_route["Report endpoints<br/>[reports.py]"]
  node_report_service["Report assembly<br/>[service.py]"]
  node_report_content["Report content<br/>[content.py]"]
  node_report_pdf["PDF renderer<br/>[pdf.py]"]
  node_report_charts["Report charts<br/>[charts.py]"]
  node_report_checks["Report checks<br/>[checks.py]"]
  node_report_formatting["Report formatting<br/>[formatting.py]"]
  node_report_store[("PDF file store<br/>[store.py]")]
  node_report_hooks["Report AI hooks<br/>[hooks.py]"]
end

subgraph group_runtime["Runtime support"]
  node_rate_limit["Report rate limits<br/>[rate_limit.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_errors["Error handling<br/>[errors.py]"]
  node_openapi_errors["Error documentation<br/>[openapi_errors.py]"]
end

node_client(("API client"))

node_client -->|"sends request"| node_app
node_app -->|"registers router"| node_health
node_app -->|"registers router"| node_metadata
node_app -->|"registers router"| node_analysis_routes
node_app -->|"registers router"| node_csv_route
node_app -->|"registers router"| node_report_route
node_app -->|"selects at startup"| node_store
node_app -->|"loads settings"| node_config
node_app -.->|"registers handlers"| node_errors
node_app -->|"installs schema"| node_openapi_errors
node_health -->|"reads provenance"| node_store
node_metadata -->|"reads metadata"| node_store
node_analysis_routes -->|"requests analysis"| node_analysis
node_analysis_routes -->|"wraps response"| node_common
node_analysis -->|"reads dataset"| node_store
node_analysis -->|"uses rules"| node_validation
node_common -->|"builds envelope"| node_schemas
node_common -->|"reads provenance"| node_store
node_store -->|"serves fixtures"| node_mock_data
node_csv_route -->|"builds export"| node_csv_export
node_csv_export -->|"encodes cells"| node_csv_codec
node_csv_export -->|"gets anomaly data"| node_analysis
node_csv_export -->|"reads dataset"| node_store
node_csv_export -->|"validates selection"| node_validation
node_report_route -->|"assembles report"| node_report_service
node_report_route -->|"renders PDF"| node_report_pdf
node_report_route -->|"saves or loads PDF"| node_report_store
node_report_route -->|"requests AI summary"| node_report_hooks
node_report_route -->|"limits requests"| node_rate_limit
node_report_service -->|"collects results"| node_store
node_report_service -->|"requests analyses"| node_analysis
node_report_service -->|"checks coverage"| node_validation
node_report_service -->|"assembles content"| node_report_content
node_report_pdf -->|"renders content"| node_report_content
node_report_pdf -->|"uses charts"| node_report_charts
node_report_pdf -->|"uses checks"| node_report_checks
node_report_pdf -->|"formats values"| node_report_formatting
node_report_hooks -->|"checks availability"| node_report_checks
node_report_hooks -->|"reads report content"| node_report_content
node_report_route -->|"accepts report contract"| node_advanced_schemas
node_analysis_routes -->|"uses result models"| node_advanced_schemas
node_app -.->|"uses API models"| node_schemas

click node_app "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/main.py"
click node_schemas "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/schemas.py"
click node_advanced_schemas "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/advanced_schemas.py"
click node_health "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/health.py"
click node_metadata "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/metadata.py"
click node_analysis_routes "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/advanced.py"
click node_common "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/common.py"
click node_store "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/store.py"
click node_validation "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/validation.py"
click node_analysis "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/advanced.py"
click node_mock_data "https://github.com/adrian-hue-pixel/trendtrace/tree/main/data/mock"
click node_csv_route "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/export.py"
click node_csv_export "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/csv_export.py"
click node_csv_codec "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/csv_codec.py"
click node_report_route "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/reports.py"
click node_report_service "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/service.py"
click node_report_content "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/content.py"
click node_report_pdf "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/pdf.py"
click node_report_charts "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/charts.py"
click node_report_checks "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/checks.py"
click node_report_formatting "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/formatting.py"
click node_report_store "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/store.py"
click node_report_hooks "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/hooks.py"
click node_rate_limit "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/rate_limit.py"
click node_config "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/config.py"
click node_errors "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/errors.py"
click node_openapi_errors "https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/openapi_errors.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_app,node_schemas,node_advanced_schemas,node_health,node_metadata,node_analysis_routes,node_common,node_client toneBlue
class node_store,node_validation,node_analysis,node_mock_data toneAmber
class node_csv_route,node_csv_export,node_csv_codec,node_report_route,node_report_service,node_report_content,node_report_pdf,node_report_charts,node_report_checks,node_report_formatting,node_report_store,node_report_hooks toneMint
class node_rate_limit,node_config,node_errors,node_openapi_errors toneRose
```

## Components

### API and contracts

- [App bootstrap](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/main.py): `backend/app/main.py`
- [Core schemas](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Advanced schemas](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/advanced_schemas.py): `backend/app/advanced_schemas.py`
- [Health endpoint](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/health.py): `backend/app/routers/health.py`
- [Metadata endpoints](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/metadata.py): `backend/app/routers/metadata.py`
- [Analysis endpoints](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/advanced.py): `backend/app/routers/advanced.py`
- [Response envelopes](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/common.py): `backend/app/routers/common.py`

### Data and analysis

- [Data store](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/store.py): `backend/app/services/store.py`
- [Request validation](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/validation.py): `backend/app/services/validation.py`
- [Analysis services](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/advanced.py): `backend/app/services/advanced.py`
- [Mock datasets](https://github.com/adrian-hue-pixel/trendtrace/tree/main/data/mock): `data/mock`

### Exports and reports

- [CSV endpoint](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/export.py): `backend/app/routers/export.py`
- [CSV builder](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/csv_export.py): `backend/app/services/csv_export.py`
- [CSV codec](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/csv_codec.py): `backend/app/services/csv_codec.py`
- [Report endpoints](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/routers/reports.py): `backend/app/routers/reports.py`
- [Report assembly](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/service.py): `backend/app/reports/service.py`
- [Report content](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/content.py): `backend/app/reports/content.py`
- [PDF renderer](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/pdf.py): `backend/app/reports/pdf.py`
- [Report charts](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/charts.py): `backend/app/reports/charts.py`
- [Report checks](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/checks.py): `backend/app/reports/checks.py`
- [Report formatting](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/formatting.py): `backend/app/reports/formatting.py`
- [PDF file store](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/store.py): `backend/app/reports/store.py`
- [Report AI hooks](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/reports/hooks.py): `backend/app/reports/hooks.py`

### Runtime support

- [Report rate limits](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/services/rate_limit.py): `backend/app/services/rate_limit.py`
- [Configuration](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/config.py): `backend/app/config.py`
- [Error handling](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/errors.py): `backend/app/errors.py`
- [Error documentation](https://github.com/adrian-hue-pixel/trendtrace/blob/main/backend/app/openapi_errors.py): `backend/app/openapi_errors.py`

### Other components

- **API client**

## Connections

- API client → App bootstrap: sends request (evidence: `README.md`)
- App bootstrap → Health endpoint: registers router (evidence: `backend/app/main.py`)
- App bootstrap → Metadata endpoints: registers router (evidence: `backend/app/main.py`)
- App bootstrap → Analysis endpoints: registers router (evidence: `backend/app/main.py`)
- App bootstrap → CSV endpoint: registers router (evidence: `backend/app/main.py`)
- App bootstrap → Report endpoints: registers router (evidence: `backend/app/main.py`)
- App bootstrap → Data store: selects at startup (evidence: `backend/app/main.py`)
- App bootstrap → Configuration: loads settings (evidence: `backend/app/main.py`)
- App bootstrap → Error handling: registers handlers (evidence: `backend/app/main.py`)
- App bootstrap → Error documentation: installs schema (evidence: `backend/app/main.py`)
- Health endpoint → Data store: reads provenance (evidence: `backend/app/routers/health.py`)
- Metadata endpoints → Data store: reads metadata (evidence: `backend/app/routers/metadata.py`)
- Analysis endpoints → Analysis services: requests analysis (evidence: `backend/app/routers/advanced.py`)
- Analysis endpoints → Response envelopes: wraps response (evidence: `backend/app/routers/advanced.py`)
- Analysis services → Data store: reads dataset (evidence: `backend/app/services/advanced.py`)
- Analysis services → Request validation: uses rules (evidence: `backend/app/services/advanced.py`)
- Response envelopes → Core schemas: builds envelope (evidence: `backend/app/routers/common.py`)
- Response envelopes → Data store: reads provenance (evidence: `backend/app/routers/common.py`)
- Data store → Mock datasets: serves fixtures (evidence: `README.md`)
- CSV endpoint → CSV builder: builds export (evidence: `backend/app/routers/export.py`)
- CSV builder → CSV codec: encodes cells (evidence: `backend/app/services/csv_export.py`)
- CSV builder → Analysis services: gets anomaly data (evidence: `backend/app/services/csv_export.py`)
- CSV builder → Data store: reads dataset (evidence: `backend/app/services/csv_export.py`)
- CSV builder → Request validation: validates selection (evidence: `backend/app/services/csv_export.py`)
- Report endpoints → Report assembly: assembles report (evidence: `backend/app/routers/reports.py`)
- Report endpoints → PDF renderer: renders PDF (evidence: `backend/app/routers/reports.py`)
- Report endpoints → PDF file store: saves or loads PDF (evidence: `backend/app/routers/reports.py`)
- Report endpoints → Report AI hooks: requests AI summary (evidence: `backend/app/routers/reports.py`)
- Report endpoints → Report rate limits: limits requests (evidence: `backend/app/routers/reports.py`)
- Report assembly → Data store: collects results (evidence: `backend/app/reports/service.py`)
- Report assembly → Analysis services: requests analyses (evidence: `backend/app/reports/service.py`)
- Report assembly → Request validation: checks coverage (evidence: `backend/app/reports/service.py`)
- Report assembly → Report content: assembles content (evidence: `backend/app/reports/service.py`)
- PDF renderer → Report content: renders content (evidence: `backend/app/reports/pdf.py`)
- PDF renderer → Report charts: uses charts (evidence: `backend/app/reports/pdf.py`)
- PDF renderer → Report checks: uses checks (evidence: `backend/app/reports/pdf.py`)
- PDF renderer → Report formatting: formats values (evidence: `backend/app/reports/pdf.py`)
- Report AI hooks → Report checks: checks availability (evidence: `backend/app/reports/hooks.py`)
- Report AI hooks → Report content: reads report content (evidence: `backend/app/reports/hooks.py`)
- Report endpoints → Advanced schemas: accepts report contract (evidence: `backend/app/routers/reports.py`)
- Analysis endpoints → Advanced schemas: uses result models (evidence: `backend/app/routers/advanced.py`)
- App bootstrap → Core schemas: uses API models