# flowcore-io/fishfacts-ai-backend architecture

> Architecture diagram of the GitHub repository flowcore-io/fishfacts-ai-backend, 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/flowcore-io/fishfacts-ai-backend
- Repository: https://github.com/flowcore-io/fishfacts-ai-backend

## Overview

Fishfacts AI Backend is a Bun/Hono service for ingesting fisheries and regulatory data, publishing events, and serving geospatial and domain read models. The documented main flow is an API request or scheduled job producing Flowcore events; pathway transformer handlers then project events into read models, including J-melding geo fragments. Other major branches cover AIS activity, regulations, and supporting datasets and reports. Some subsystem links are grounded only in README statements or source-index references; unsampled implementation details are not inferred.

Main entry points: [`src/pathways.ts`](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/pathways.ts) (Pathway Runtime), [`src/app.ts`](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/app.ts) (HTTP Application), [`src/jobs/runner.ts`](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jobs/runner.ts) (Job Runner), [`src/regulations/routes.ts`](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/routes.ts) (Regulation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Jobs"]
  node_app["HTTP Application<br/>[app.ts]"]
  node_jobrunner["Job Runner<br/>[runner.ts]"]
  node_jobstate[("Job State<br/>[state-store.ts]")]
end

subgraph group_events["Events and Projections"]
  node_pathways["Pathway Runtime<br/>[pathways.ts]"]
  node_eventcontracts["Event Contracts<br/>[contracts.ts]"]
  node_eventrepo[("Event Repository<br/>[repository.ts]")]
  node_jmjobs["J-melding Assembly"]
  node_geoprojector["Geo Projector<br/>[geo-projector.ts]"]
  node_georepo[("Geo Read Model<br/>[geo-repository.ts]")]
end

subgraph group_regulations["Regulations"]
  node_reg_routes["Regulation API<br/>[routes.ts]"]
  node_reg_runtime["Command Runtime<br/>[command-runtime.ts]"]
  node_reg_state[("Coastal State<br/>[coastal-state.ts]")]
  node_reg_publish[("Published Read Model")]
end

subgraph group_ais["AIS Analytics"]
  node_ais_routes["AIS API<br/>[routes.ts]"]
  node_ais_activity["Activity Queries<br/>[activity-source.ts]"]
  node_ais_cache[("Activity Cache<br/>[activity-cache.ts]")]
  node_ais_ch[("ClickHouse Repository")]
end

subgraph group_data["Other Data Products"]
  node_financials["Financial Reports<br/>[repository.ts]"]
  node_gebco["GEBCO Ingestion<br/>[ingester.ts]"]
  node_poi["POI Repository<br/>[repository.ts]"]
  node_reports["Reports API<br/>[routes.ts]"]
  node_logasavn["Corpus Index<br/>[sweep.ts]"]
end

node_client(("API Client"))
node_usable["Usable Service"]
node_postgres[("PostgreSQL")]
node_flowcore["Flowcore"]

node_client -->|"sends requests"| node_app
node_app -->|"writes events"| node_pathways
node_app -->|"queries geo"| node_georepo
node_client -->|"runs jobs"| node_jobrunner
node_jobrunner -->|"tracks runs"| node_jobstate
node_jobrunner -.->|"dispatches job"| node_jmjobs
node_jmjobs -->|"emits announcements"| node_flowcore
node_flowcore -->|"delivers events"| node_pathways
node_pathways -->|"dispatches projection"| node_geoprojector
node_geoprojector -->|"upserts geo rows"| node_georepo
node_georepo -->|"reads and writes"| node_postgres
node_pathways -.->|"projects generic events"| node_eventrepo
node_eventrepo -->|"stores events"| node_postgres
node_app -.->|"mounts API"| node_reg_routes
node_reg_routes -->|"executes commands"| node_reg_runtime
node_reg_publish -->|"reads published data"| node_postgres
node_reg_routes -->|"uses published reads"| node_reg_publish
node_ais_routes -->|"queries analytics"| node_ais_ch
node_ais_routes -->|"queries activity"| node_ais_activity
node_ais_activity -->|"uses cached results"| node_ais_cache
node_ais_cache -->|"stores cache"| node_postgres
node_financials -->|"uses database"| node_postgres
node_gebco -->|"publishes ingestion"| node_pathways
node_poi -->|"reads fragments"| node_usable
node_reports -->|"creates reports"| node_usable
node_logasavn -->|"publishes index"| node_usable

click node_app "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/app.ts"
click node_jobrunner "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jobs/runner.ts"
click node_jobstate "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jobs/state-store.ts"
click node_pathways "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/pathways.ts"
click node_eventcontracts "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/events/contracts.ts"
click node_eventrepo "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/events/repository.ts"
click node_jmjobs "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jobs/jmelding-chunk-assembler.ts"
click node_geoprojector "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jmelding/geo-projector.ts"
click node_georepo "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jmelding/geo-repository.ts"
click node_reg_routes "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/routes.ts"
click node_reg_runtime "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/command-runtime.ts"
click node_reg_state "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/coastal-state.ts"
click node_reg_publish "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/published-repository.ts"
click node_ais_routes "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/ais/routes.ts"
click node_ais_activity "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/ais/activity-source.ts"
click node_ais_cache "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/ais/activity-cache.ts"
click node_ais_ch "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/ais/clickhouse-repository.ts"
click node_financials "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/financials/repository.ts"
click node_gebco "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/gebco/ingester.ts"
click node_poi "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/poi/repository.ts"
click node_reports "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/reports/routes.ts"
click node_logasavn "https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/logasavn/sweep.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_app,node_jobrunner,node_jobstate,node_client toneBlue
class node_pathways,node_eventcontracts,node_eventrepo,node_jmjobs,node_geoprojector,node_georepo,node_postgres toneAmber
class node_reg_routes,node_reg_runtime,node_reg_state,node_reg_publish toneMint
class node_ais_routes,node_ais_activity,node_ais_cache,node_ais_ch toneRose
class node_financials,node_gebco,node_poi,node_reports,node_logasavn,node_usable,node_flowcore toneIndigo
```

## Components

### API and Jobs

- [HTTP Application](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/app.ts): `src/app.ts`
- [Job Runner](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jobs/runner.ts): `src/jobs/runner.ts`
- [Job State](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jobs/state-store.ts): `src/jobs/state-store.ts`

### Events and Projections

- [Pathway Runtime](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/pathways.ts): `src/pathways.ts`
- [Event Contracts](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/events/contracts.ts): `src/events/contracts.ts`
- [Event Repository](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/events/repository.ts): `src/events/repository.ts`
- [J-melding Assembly](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jobs/jmelding-chunk-assembler.ts): `src/jobs/jmelding-chunk-assembler.ts`
- [Geo Projector](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jmelding/geo-projector.ts): `src/jmelding/geo-projector.ts`
- [Geo Read Model](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/jmelding/geo-repository.ts): `src/jmelding/geo-repository.ts`

### Regulations

- [Regulation API](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/routes.ts): `src/regulations/routes.ts`
- [Command Runtime](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/command-runtime.ts): `src/regulations/command-runtime.ts`
- [Coastal State](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/coastal-state.ts): `src/regulations/coastal-state.ts`
- [Published Read Model](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/regulations/published-repository.ts): `src/regulations/published-repository.ts`

### AIS Analytics

- [AIS API](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/ais/routes.ts): `src/ais/routes.ts`
- [Activity Queries](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/ais/activity-source.ts): `src/ais/activity-source.ts`
- [Activity Cache](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/ais/activity-cache.ts): `src/ais/activity-cache.ts`
- [ClickHouse Repository](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/ais/clickhouse-repository.ts): `src/ais/clickhouse-repository.ts`

### Other Data Products

- [Financial Reports](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/financials/repository.ts): `src/financials/repository.ts`
- [GEBCO Ingestion](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/gebco/ingester.ts): `src/gebco/ingester.ts`
- [POI Repository](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/poi/repository.ts): `src/poi/repository.ts`
- [Reports API](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/reports/routes.ts): `src/reports/routes.ts`
- [Corpus Index](https://github.com/flowcore-io/fishfacts-ai-backend/blob/main/src/logasavn/sweep.ts): `src/logasavn/sweep.ts`

### Other components

- **API Client**
- **Usable Service**
- **PostgreSQL**
- **Flowcore**

## Connections

- API Client → HTTP Application: sends requests (evidence: `src/app.ts`)
- HTTP Application → Pathway Runtime: writes events (evidence: `src/app.ts`)
- HTTP Application → Geo Read Model: queries geo (evidence: `src/app.ts`)
- API Client → Job Runner: runs jobs (evidence: `README.md`)
- Job Runner → Job State: tracks runs (evidence: `src/jobs/runner.ts`)
- Job Runner → J-melding Assembly: dispatches job
- J-melding Assembly → Flowcore: emits announcements (evidence: `README.md`)
- Flowcore → Pathway Runtime: delivers events (evidence: `README.md`)
- Pathway Runtime → Geo Projector: dispatches projection (evidence: `src/pathways.ts`)
- Geo Projector → Geo Read Model: upserts geo rows (evidence: `README.md`)
- Geo Read Model → PostgreSQL: reads and writes (evidence: `src/jmelding/geo-repository.ts`)
- Pathway Runtime → Event Repository: projects generic events (evidence: `src/pathways.ts`)
- Event Repository → PostgreSQL: stores events (evidence: `src/events/repository.ts`)
- HTTP Application → Regulation API: mounts API (evidence: `src/app.ts`)
- Regulation API → Command Runtime: executes commands (evidence: `src/regulations/routes.ts`)
- Published Read Model → PostgreSQL: reads published data (evidence: `src/regulations/published-repository.ts`)
- Regulation API → Published Read Model: uses published reads (evidence: `src/regulations/published-routes.ts`)
- AIS API → ClickHouse Repository: queries analytics (evidence: `src/ais/routes.ts`)
- AIS API → Activity Queries: queries activity
- Activity Queries → Activity Cache: uses cached results (evidence: `src/ais/activity-routes.ts`)
- Activity Cache → PostgreSQL: stores cache (evidence: `src/ais/activity-cache.ts`)
- Financial Reports → PostgreSQL: uses database (evidence: `src/financials/repository.ts`)
- GEBCO Ingestion → Pathway Runtime: publishes ingestion (evidence: `src/jobs/gebco-ingest.ts`)
- POI Repository → Usable Service: reads fragments (evidence: `src/poi/repository.ts`)
- Reports API → Usable Service: creates reports (evidence: `src/reports/routes.ts`)
- Corpus Index → Usable Service: publishes index (evidence: `README.md`)
