# stuv1983/afldb architecture

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

- Interactive diagram: https://gitdiagram.com/stuv1983/afldb
- Repository: https://github.com/stuv1983/afldb

## Overview

AFLDB is a closed-beta historical VFL/AFL and separately scoped AFLW statistics reference, with public browsing, records, comparisons and several kinds of search, plus audited administration and data-maintenance workflows. A typical user asks a question or opens a statistical page; the application resolves it through typed query logic against PostgreSQL and presents results. The README documents a deterministic natural-language search pipeline and the V2 acquisition, derived-data and operations capabilities. Source excerpts are limited, so links for unsampled areas use documented relationships rather than presumed implementation calls.

Main entry points: [`src/app/search`](https://github.com/stuv1983/afldb/tree/main/src/app/search) (Search pages), [`src/app`](https://github.com/stuv1983/afldb/tree/main/src/app) (Statistics pages), [`src/db/queries`](https://github.com/stuv1983/afldb/tree/main/src/db/queries) (Statistics queries), [`src/search/nl/parser.ts`](https://github.com/stuv1983/afldb/blob/main/src/search/nl/parser.ts) (Question parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public statistics"]
  node_public_app["Statistics pages"]
  node_stats_queries["Statistics queries"]
  node_database[("PostgreSQL")]
end

subgraph group_search["Search tools"]
  node_search_page["Search pages"]
  node_nl_parser["Question parser<br/>[parser.ts]"]
  node_nl_plan["Query planner<br/>[plan.ts]"]
  node_nl_execute["Query executor<br/>[execute.ts]"]
  node_query_builder["Statistical query builder"]
  node_grid_solver["Grid Solver"]
end

subgraph group_admin["Administration"]
  node_admin_ops["Operations centre"]
  node_admin_awards["Awards curation<br/>[curated-awards.ts]"]
end

subgraph group_platform["V2 data platform"]
  node_acquisition["Acquisition pipeline<br/>[pipeline.ts]"]
  node_domain_rules["Domain controls"]
  node_derived["Derived statistics"]
  node_db_package["Database utilities"]
  node_historical_store[("Historical dataset")]
end

subgraph group_operations["Data operations"]
  node_current_season["Current-season AFL API<br/>[afl-api-client.ts]"]
  node_csv_intake["Vetted CSV intake<br/>[pipeline.ts]"]
end

node_visitor(("Visitor"))
node_search_user(("Search user"))
node_admin_user(("Administrator"))

node_visitor -->|"browses"| node_public_app
node_public_app -.->|"requests statistics"| node_stats_queries
node_stats_queries -.->|"queries"| node_database
node_search_user -->|"asks question"| node_search_page
node_search_page -->|"parses question"| node_nl_parser
node_nl_parser -->|"plans query"| node_nl_plan
node_nl_plan -->|"compiles query"| node_nl_execute
node_nl_execute -->|"queries PostgreSQL"| node_database
node_search_page -->|"offers typed filters"| node_query_builder
node_search_page -->|"offers grid questions"| node_grid_solver
node_admin_user -->|"reviews operations"| node_admin_ops
node_admin_user -->|"curates awards"| node_admin_awards
node_acquisition -.->|"acquires data"| node_historical_store
node_current_season -.->|"supplies updates"| node_acquisition
node_csv_intake -.->|"stages submissions"| node_historical_store
node_domain_rules -.->|"defines coverage"| node_historical_store
node_historical_store -->|"rebuilds aggregates"| node_derived
node_db_package -->|"produces manifests"| node_historical_store
node_admin_ops -.->|"reviews determinations"| node_derived

click node_public_app "https://github.com/stuv1983/afldb/tree/main/src/app"
click node_stats_queries "https://github.com/stuv1983/afldb/tree/main/src/db/queries"
click node_search_page "https://github.com/stuv1983/afldb/tree/main/src/app/search"
click node_nl_parser "https://github.com/stuv1983/afldb/blob/main/src/search/nl/parser.ts"
click node_nl_plan "https://github.com/stuv1983/afldb/blob/main/src/search/nl/plan.ts"
click node_nl_execute "https://github.com/stuv1983/afldb/blob/main/src/db/queries/nl/execute.ts"
click node_query_builder "https://github.com/stuv1983/afldb/blob/main/src/search/query-builder-spec.ts"
click node_grid_solver "https://github.com/stuv1983/afldb/blob/main/src/search/grid-solver-spec.ts"
click node_admin_ops "https://github.com/stuv1983/afldb/tree/main/src/app/admin/operations"
click node_admin_awards "https://github.com/stuv1983/afldb/blob/main/packages/admin/src/curated-awards.ts"
click node_acquisition "https://github.com/stuv1983/afldb/blob/main/packages/acquisition/src/pipeline.ts"
click node_domain_rules "https://github.com/stuv1983/afldb/blob/main/packages/domain/src/coverage-registry.ts"
click node_derived "https://github.com/stuv1983/afldb/tree/main/packages/derived/src"
click node_db_package "https://github.com/stuv1983/afldb/tree/main/packages/db/src"
click node_current_season "https://github.com/stuv1983/afldb/blob/main/src/lib/acquisition/afl-api-client.ts"
click node_csv_intake "https://github.com/stuv1983/afldb/blob/main/src/lib/ingest/pipeline.ts"

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_public_app,node_stats_queries,node_database,node_search_user toneBlue
class node_search_page,node_nl_parser,node_nl_plan,node_nl_execute,node_query_builder,node_grid_solver toneAmber
class node_admin_ops,node_admin_awards toneMint
class node_acquisition,node_domain_rules,node_derived,node_db_package,node_historical_store toneRose
class node_current_season,node_csv_intake,node_visitor,node_admin_user toneIndigo
```

## Components

### Public statistics

- [Statistics pages](https://github.com/stuv1983/afldb/tree/main/src/app): `src/app`
- [Statistics queries](https://github.com/stuv1983/afldb/tree/main/src/db/queries): `src/db/queries`
- **PostgreSQL**

### Search tools

- [Search pages](https://github.com/stuv1983/afldb/tree/main/src/app/search): `src/app/search`
- [Question parser](https://github.com/stuv1983/afldb/blob/main/src/search/nl/parser.ts): `src/search/nl/parser.ts`
- [Query planner](https://github.com/stuv1983/afldb/blob/main/src/search/nl/plan.ts): `src/search/nl/plan.ts`
- [Query executor](https://github.com/stuv1983/afldb/blob/main/src/db/queries/nl/execute.ts): `src/db/queries/nl/execute.ts`
- [Statistical query builder](https://github.com/stuv1983/afldb/blob/main/src/search/query-builder-spec.ts): `src/search/query-builder-spec.ts`
- [Grid Solver](https://github.com/stuv1983/afldb/blob/main/src/search/grid-solver-spec.ts): `src/search/grid-solver-spec.ts`

### Administration

- [Operations centre](https://github.com/stuv1983/afldb/tree/main/src/app/admin/operations): `src/app/admin/operations`
- [Awards curation](https://github.com/stuv1983/afldb/blob/main/packages/admin/src/curated-awards.ts): `packages/admin/src/curated-awards.ts`

### V2 data platform

- [Acquisition pipeline](https://github.com/stuv1983/afldb/blob/main/packages/acquisition/src/pipeline.ts): `packages/acquisition/src/pipeline.ts`
- [Domain controls](https://github.com/stuv1983/afldb/blob/main/packages/domain/src/coverage-registry.ts): `packages/domain/src/coverage-registry.ts`
- [Derived statistics](https://github.com/stuv1983/afldb/tree/main/packages/derived/src): `packages/derived/src`
- [Database utilities](https://github.com/stuv1983/afldb/tree/main/packages/db/src): `packages/db/src`
- **Historical dataset**

### Data operations

- [Current-season AFL API](https://github.com/stuv1983/afldb/blob/main/src/lib/acquisition/afl-api-client.ts): `src/lib/acquisition/afl-api-client.ts`
- [Vetted CSV intake](https://github.com/stuv1983/afldb/blob/main/src/lib/ingest/pipeline.ts): `src/lib/ingest/pipeline.ts`

### Other components

- **Visitor**
- **Search user**
- **Administrator**

## Connections

- Visitor → Statistics pages: browses (evidence: `README.md`)
- Statistics pages → Statistics queries: requests statistics (evidence: `src/app/api/early-access/route.ts`)
- Statistics queries → PostgreSQL: queries
- Search user → Search pages: asks question (evidence: `README.md`)
- Search pages → Question parser: parses question (evidence: `README.md`)
- Question parser → Query planner: plans query (evidence: `README.md`)
- Query planner → Query executor: compiles query (evidence: `README.md`)
- Query executor → PostgreSQL: queries PostgreSQL (evidence: `README.md`)
- Search pages → Statistical query builder: offers typed filters (evidence: `README.md`)
- Search pages → Grid Solver: offers grid questions (evidence: `README.md`)
- Administrator → Operations centre: reviews operations (evidence: `README.md`)
- Administrator → Awards curation: curates awards (evidence: `README.md`)
- Acquisition pipeline → Historical dataset: acquires data
- Current-season AFL API → Acquisition pipeline: supplies updates
- Vetted CSV intake → Historical dataset: stages submissions
- Domain controls → Historical dataset: defines coverage
- Historical dataset → Derived statistics: rebuilds aggregates (evidence: `README.md`)
- Database utilities → Historical dataset: produces manifests (evidence: `README.md`)
- Operations centre → Derived statistics: reviews determinations
