# daniel-dos/ff-codex architecture

> Architecture diagram of the GitHub repository daniel-dos/ff-codex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/daniel-dos/ff-codex
- Repository: https://github.com/daniel-dos/ff-codex

## Overview

FF Codex is a Rust/Axum REST API for querying and managing Final Fantasy games and characters. The main workflow is HTTP routing to handlers, service-level orchestration, SQLx repositories, and PostgreSQL, with handlers converting domain results to API responses. It supports game filtering, lookup, creation and deletion; character listing, lookup, creation and game-character associations; and a health endpoint. The README documents these layers and capabilities; some route, server, DTO, and character repository implementation details were not sampled, so uncertain wiring is omitted.

Main entry points: [`app/src/main.rs`](https://github.com/daniel-dos/ff-codex/blob/main/app/src/main.rs) (Application bootstrap), [`app/src/rest/routes/router.rs`](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/routes/router.rs) (API router), [`app/src/rest/handler/games_handler.rs`](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/handler/games_handler.rs) (Game handlers), [`app/src/rest/handler/characters_handler.rs`](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/handler/characters_handler.rs) (Character handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_router["API router<br/>[router.rs]"]
  node_game_routes["Game routes<br/>[games.rs]"]
  node_character_routes["Character routes<br/>[characters.rs]"]
  node_game_handler["Game handlers<br/>[games_handler.rs]"]
  node_character_handler["Character handlers"]
  node_health["Health handler<br/>[health.rs]"]
  node_dto["API DTOs"]
  node_app_error["API errors<br/>[error.rs]"]
  node_app_state["App state<br/>[app_state.rs]"]
  node_server["HTTP server<br/>[server_app.rs]"]
end

subgraph group_logic["Services and Domain"]
  node_game_service["Game service<br/>[game_service.rs]"]
  node_character_service["Character service"]
  node_domain["Domain models"]
end

subgraph group_persistence["Persistence"]
  node_game_repo["Game repository<br/>[game.rs]"]
  node_character_repo["Character repository<br/>[character.rs]"]
  node_game_sql["Game queries"]
  node_character_sql["Character queries"]
end

node_client(("API client"))
node_postgres[("PostgreSQL")]
node_bootstrap["Application bootstrap<br/>[main.rs]"]

node_client -->|"sends requests"| node_router
node_router -->|"dispatches"| node_game_routes
node_router -->|"dispatches"| node_character_routes
node_router -->|"dispatches"| node_health
node_game_routes -->|"routes to"| node_game_handler
node_character_routes -->|"routes to"| node_character_handler
node_game_handler -->|"calls"| node_game_service
node_character_handler -->|"calls"| node_character_service
node_game_handler -->|"maps responses"| node_dto
node_character_handler -->|"maps responses"| node_dto
node_game_handler -->|"maps errors"| node_app_error
node_character_handler -->|"maps errors"| node_app_error
node_game_service -->|"delegates queries"| node_game_repo
node_character_service -->|"delegates queries"| node_character_repo
node_game_service -->|"uses models"| node_domain
node_character_service -->|"uses models"| node_domain
node_game_repo -->|"executes queries"| node_game_sql
node_character_repo -->|"executes queries"| node_character_sql
node_game_repo -->|"reads and writes"| node_postgres
node_character_repo -->|"reads and writes"| node_postgres
node_bootstrap -->|"connects pool"| node_postgres
node_bootstrap -->|"constructs"| node_game_repo
node_bootstrap -->|"constructs"| node_character_repo
node_bootstrap -->|"injects services"| node_app_state
node_bootstrap -->|"builds"| node_router
node_bootstrap -->|"starts"| node_server
node_server -->|"serves"| node_router
node_game_handler -->|"returns API response"| node_client
node_character_handler -->|"returns API response"| node_client

click node_router "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/routes/router.rs"
click node_game_routes "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/routes/games.rs"
click node_character_routes "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/routes/characters.rs"
click node_game_handler "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/handler/games_handler.rs"
click node_character_handler "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/handler/characters_handler.rs"
click node_health "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/handler/health.rs"
click node_dto "https://github.com/daniel-dos/ff-codex/tree/main/app/src/rest/dto"
click node_app_error "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/error.rs"
click node_app_state "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/app_state.rs"
click node_server "https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/server_app.rs"
click node_game_service "https://github.com/daniel-dos/ff-codex/blob/main/app/src/service/game_service.rs"
click node_character_service "https://github.com/daniel-dos/ff-codex/blob/main/app/src/service/characters_service.rs"
click node_domain "https://github.com/daniel-dos/ff-codex/tree/main/app/src/domain"
click node_game_repo "https://github.com/daniel-dos/ff-codex/blob/main/app/src/repository/game.rs"
click node_character_repo "https://github.com/daniel-dos/ff-codex/blob/main/app/src/repository/character.rs"
click node_game_sql "https://github.com/daniel-dos/ff-codex/tree/main/app/sql/games"
click node_character_sql "https://github.com/daniel-dos/ff-codex/tree/main/app/sql/characters"
click node_bootstrap "https://github.com/daniel-dos/ff-codex/blob/main/app/src/main.rs"

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_router,node_game_routes,node_character_routes,node_game_handler,node_character_handler,node_health,node_dto,node_app_error,node_app_state,node_server,node_client toneBlue
class node_game_service,node_character_service,node_domain,node_postgres toneAmber
class node_game_repo,node_character_repo,node_game_sql,node_character_sql toneMint
class node_bootstrap toneTeal
```

## Components

### HTTP API

- [API router](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/routes/router.rs): `app/src/rest/routes/router.rs`
- [Game routes](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/routes/games.rs): `app/src/rest/routes/games.rs`
- [Character routes](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/routes/characters.rs): `app/src/rest/routes/characters.rs`
- [Game handlers](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/handler/games_handler.rs): `app/src/rest/handler/games_handler.rs`
- [Character handlers](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/handler/characters_handler.rs): `app/src/rest/handler/characters_handler.rs`
- [Health handler](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/handler/health.rs): `app/src/rest/handler/health.rs`
- [API DTOs](https://github.com/daniel-dos/ff-codex/tree/main/app/src/rest/dto): `app/src/rest/dto`
- [API errors](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/error.rs): `app/src/rest/error.rs`
- [App state](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/app_state.rs): `app/src/rest/app_state.rs`
- [HTTP server](https://github.com/daniel-dos/ff-codex/blob/main/app/src/rest/server_app.rs): `app/src/rest/server_app.rs`

### Services and Domain

- [Game service](https://github.com/daniel-dos/ff-codex/blob/main/app/src/service/game_service.rs): `app/src/service/game_service.rs`
- [Character service](https://github.com/daniel-dos/ff-codex/blob/main/app/src/service/characters_service.rs): `app/src/service/characters_service.rs`
- [Domain models](https://github.com/daniel-dos/ff-codex/tree/main/app/src/domain): `app/src/domain`

### Persistence

- [Game repository](https://github.com/daniel-dos/ff-codex/blob/main/app/src/repository/game.rs): `app/src/repository/game.rs`
- [Character repository](https://github.com/daniel-dos/ff-codex/blob/main/app/src/repository/character.rs): `app/src/repository/character.rs`
- [Game queries](https://github.com/daniel-dos/ff-codex/tree/main/app/sql/games): `app/sql/games`
- [Character queries](https://github.com/daniel-dos/ff-codex/tree/main/app/sql/characters): `app/sql/characters`

### Other components

- **API client**
- **PostgreSQL**
- [Application bootstrap](https://github.com/daniel-dos/ff-codex/blob/main/app/src/main.rs): `app/src/main.rs`

## Connections

- API client → API router: sends requests
- API router → Game routes: dispatches
- API router → Character routes: dispatches
- API router → Health handler: dispatches
- Game routes → Game handlers: routes to
- Character routes → Character handlers: routes to
- Game handlers → Game service: calls
- Character handlers → Character service: calls
- Game handlers → API DTOs: maps responses
- Character handlers → API DTOs: maps responses
- Game handlers → API errors: maps errors
- Character handlers → API errors: maps errors
- Game service → Game repository: delegates queries
- Character service → Character repository: delegates queries
- Game service → Domain models: uses models
- Character service → Domain models: uses models
- Game repository → Game queries: executes queries
- Character repository → Character queries: executes queries
- Game repository → PostgreSQL: reads and writes
- Character repository → PostgreSQL: reads and writes
- Application bootstrap → PostgreSQL: connects pool
- Application bootstrap → Game repository: constructs
- Application bootstrap → Character repository: constructs
- Application bootstrap → App state: injects services
- Application bootstrap → API router: builds
- Application bootstrap → HTTP server: starts
- HTTP server → API router: serves
- Game handlers → API client: returns API response
- Character handlers → API client: returns API response