# f3rren/century-road-backend architecture

> Architecture diagram of the GitHub repository f3rren/century-road-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/f3rren/century-road-backend
- Repository: https://github.com/f3rren/century-road-backend

## Overview

Century Road is a three-service backend: the gateway is the browser-facing entry point, auth-service manages identity and tokens, and history-service serves Wikipedia-based history plus discovery, editorial, reporting, and usage features. The shown on-this-day path validates a query, loads feeds through a cache, records a view, and returns an envelope. Other history capabilities are documented, but their controller-to-service wiring is not sampled; those links are marked unverified rather than inferred as direct calls.

Main entry points: [`service/history-service/src/main/java/centuryroad/history/controller/OnThisDayController.java`](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/controller/OnThisDayController.java) (History endpoints), [`service/auth-service/src/main/java/centuryroad/auth/service/SessionService.java`](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/SessionService.java) (Session service), [`service/gateway/src/main/java/centuryroad/gateway/GatewayApplication.java`](https://github.com/f3rren/century-road-backend/blob/main/service/gateway/src/main/java/centuryroad/gateway/GatewayApplication.java) (Gateway routing), [`service/auth-service/src/main/java/centuryroad/auth/controller/AuthController.java`](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/controller/AuthController.java) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["API gateway"]
  node_gateway["Gateway routing"]
end

subgraph group_identity["Identity and sessions"]
  node_auth_api["Auth endpoints"]
  node_admin_api["User administration"]
  node_session["Session service"]
  node_auth_logic["Identity management<br/>[AuthService.java]"]
  node_user_service["User lookup<br/>[UserService.java]"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_refresh["Refresh tokens"]
  node_users_db[("Identity database<br/>[User.java]")]
end

subgraph group_history["Historical feeds"]
  node_history_api["History endpoints"]
  node_day_query["Query validation"]
  node_day_service["On-this-day service"]
  node_feed_cache["Feed cache<br/>[FeedCache.java]"]
end

subgraph group_discovery["Discovery and editorial"]
  node_timeline_api["Timeline and discovery"]
  node_timeline["Timeline queries"]
  node_editorial["Editorial catalog"]
  node_reports_api["Error reports"]
  node_reports["Report handling<br/>[ReportService.java]"]
  node_history_db[("History database")]
end

node_browser(("Browser client"))
node_proxy["TLS proxy"]
node_wikimedia["Wikipedia feeds"]

node_browser -->|"sends HTTPS"| node_proxy
node_proxy -->|"forwards requests"| node_gateway
node_gateway -->|"routes auth"| node_auth_api
node_gateway -->|"routes history"| node_history_api
node_auth_api -.->|"delegates to"| node_session
node_session -->|"authenticates with"| node_auth_logic
node_session -->|"issues tokens"| node_jwt
node_session -->|"rotates tokens"| node_refresh
node_auth_logic -->|"reads and writes"| node_users_db
node_admin_api -->|"manages users"| node_user_service
node_user_service -->|"looks up users"| node_users_db
node_history_api -->|"validates request"| node_day_query
node_history_api -->|"requests events"| node_day_service
node_day_service -->|"loads feeds"| node_feed_cache
node_feed_cache -.->|"fetches feeds"| node_wikimedia
node_history_api -.->|"also exposes"| node_timeline_api
node_timeline_api -.->|"queries index"| node_timeline
node_timeline -->|"reads index"| node_history_db
node_history_api -.->|"also exposes"| node_reports_api
node_reports_api -.->|"submits reports"| node_reports
node_reports -->|"checks targets"| node_editorial

click node_gateway "https://github.com/f3rren/century-road-backend/blob/main/service/gateway/src/main/java/centuryroad/gateway/GatewayApplication.java"
click node_auth_api "https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/controller/AuthController.java"
click node_admin_api "https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/controller/AdminUserController.java"
click node_session "https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/SessionService.java"
click node_auth_logic "https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/AuthService.java"
click node_user_service "https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/UserService.java"
click node_jwt "https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/JwtService.java"
click node_refresh "https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/RefreshTokenService.java"
click node_users_db "https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/model/User.java"
click node_history_api "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/controller/OnThisDayController.java"
click node_day_query "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/query/OnThisDayQuery.java"
click node_day_service "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/OnThisDayService.java"
click node_feed_cache "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/FeedCache.java"
click node_timeline_api "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/controller/TimelineController.java"
click node_timeline "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/TimelineService.java"
click node_editorial "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/EditorialCatalog.java"
click node_reports_api "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/controller/ReportsController.java"
click node_reports "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/ReportService.java"
click node_history_db "https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/repository/TimelineEventRepository.java"

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_gateway,node_browser toneBlue
class node_auth_api,node_admin_api,node_session,node_auth_logic,node_user_service,node_jwt,node_refresh,node_users_db toneAmber
class node_history_api,node_day_query,node_day_service,node_feed_cache toneMint
class node_timeline_api,node_timeline,node_editorial,node_reports_api,node_reports,node_history_db toneRose
class node_proxy,node_wikimedia toneIndigo
```

## Components

### API gateway

- [Gateway routing](https://github.com/f3rren/century-road-backend/blob/main/service/gateway/src/main/java/centuryroad/gateway/GatewayApplication.java): `service/gateway/src/main/java/centuryroad/gateway/GatewayApplication.java`

### Identity and sessions

- [Auth endpoints](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/controller/AuthController.java): `service/auth-service/src/main/java/centuryroad/auth/controller/AuthController.java`
- [User administration](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/controller/AdminUserController.java): `service/auth-service/src/main/java/centuryroad/auth/controller/AdminUserController.java`
- [Session service](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/SessionService.java): `service/auth-service/src/main/java/centuryroad/auth/service/SessionService.java`
- [Identity management](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/AuthService.java): `service/auth-service/src/main/java/centuryroad/auth/service/AuthService.java`
- [User lookup](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/UserService.java): `service/auth-service/src/main/java/centuryroad/auth/service/UserService.java`
- [JWT service](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/JwtService.java): `service/auth-service/src/main/java/centuryroad/auth/service/JwtService.java`
- [Refresh tokens](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/service/RefreshTokenService.java): `service/auth-service/src/main/java/centuryroad/auth/service/RefreshTokenService.java`
- [Identity database](https://github.com/f3rren/century-road-backend/blob/main/service/auth-service/src/main/java/centuryroad/auth/model/User.java): `service/auth-service/src/main/java/centuryroad/auth/model/User.java`

### Historical feeds

- [History endpoints](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/controller/OnThisDayController.java): `service/history-service/src/main/java/centuryroad/history/controller/OnThisDayController.java`
- [Query validation](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/query/OnThisDayQuery.java): `service/history-service/src/main/java/centuryroad/history/query/OnThisDayQuery.java`
- [On-this-day service](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/OnThisDayService.java): `service/history-service/src/main/java/centuryroad/history/service/OnThisDayService.java`
- [Feed cache](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/FeedCache.java): `service/history-service/src/main/java/centuryroad/history/service/FeedCache.java`

### Discovery and editorial

- [Timeline and discovery](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/controller/TimelineController.java): `service/history-service/src/main/java/centuryroad/history/controller/TimelineController.java`
- [Timeline queries](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/TimelineService.java): `service/history-service/src/main/java/centuryroad/history/service/TimelineService.java`
- [Editorial catalog](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/EditorialCatalog.java): `service/history-service/src/main/java/centuryroad/history/service/EditorialCatalog.java`
- [Error reports](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/controller/ReportsController.java): `service/history-service/src/main/java/centuryroad/history/controller/ReportsController.java`
- [Report handling](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/service/ReportService.java): `service/history-service/src/main/java/centuryroad/history/service/ReportService.java`
- [History database](https://github.com/f3rren/century-road-backend/blob/main/service/history-service/src/main/java/centuryroad/history/repository/TimelineEventRepository.java): `service/history-service/src/main/java/centuryroad/history/repository/TimelineEventRepository.java`

### Other components

- **Browser client**
- **TLS proxy**
- **Wikipedia feeds**

## Connections

- Browser client → TLS proxy: sends HTTPS (evidence: `README.md`)
- TLS proxy → Gateway routing: forwards requests (evidence: `README.md`)
- Gateway routing → Auth endpoints: routes auth (evidence: `README.md`)
- Gateway routing → History endpoints: routes history (evidence: `README.md`)
- Auth endpoints → Session service: delegates to (evidence: `service/auth-service/src/main/java/centuryroad/auth/controller/AuthController.java`)
- Session service → Identity management: authenticates with (evidence: `service/auth-service/src/main/java/centuryroad/auth/service/SessionService.java`)
- Session service → JWT service: issues tokens (evidence: `service/auth-service/src/main/java/centuryroad/auth/service/SessionService.java`)
- Session service → Refresh tokens: rotates tokens (evidence: `service/auth-service/src/main/java/centuryroad/auth/service/SessionService.java`)
- Identity management → Identity database: reads and writes (evidence: `service/auth-service/src/main/java/centuryroad/auth/service/AuthService.java`)
- User administration → User lookup: manages users (evidence: `service/auth-service/src/main/java/centuryroad/auth/controller/AdminUserController.java`)
- User lookup → Identity database: looks up users (evidence: `service/auth-service/src/main/java/centuryroad/auth/service/UserService.java`)
- History endpoints → Query validation: validates request (evidence: `service/history-service/src/main/java/centuryroad/history/controller/OnThisDayController.java`)
- History endpoints → On-this-day service: requests events (evidence: `service/history-service/src/main/java/centuryroad/history/controller/OnThisDayController.java`)
- On-this-day service → Feed cache: loads feeds (evidence: `service/history-service/src/main/java/centuryroad/history/service/OnThisDayService.java`)
- Feed cache → Wikipedia feeds: fetches feeds
- History endpoints → Timeline and discovery: also exposes
- Timeline and discovery → Timeline queries: queries index
- Timeline queries → History database: reads index (evidence: `service/history-service/src/main/java/centuryroad/history/service/TimelineService.java`)
- History endpoints → Error reports: also exposes
- Error reports → Report handling: submits reports
- Report handling → Editorial catalog: checks targets (evidence: `service/history-service/src/main/java/centuryroad/history/service/ReportService.java`)
