# jack26-bit/iko architecture

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

- Interactive diagram: https://gitdiagram.com/jack26-bit/iko
- Repository: https://github.com/jack26-bit/iko

## Overview

IKO is documented as a Flutter productivity RPG backed by a FastAPI service. The principal evidenced workflow is a client request reaching the API, resolving a user and database session, then creating or completing a quest; completion awards XP and coins and updates the user’s streak. The supplied tree contains no Flutter/Dart application sources, so the client is shown only as an external actor. Other README capabilities are represented as documented product scope, not as verified implementations. Evidence is limited to the README and excerpted backend files.

Main entry points: [`backend/api/endpoints/quests.py`](https://github.com/jack26-bit/iko/blob/main/backend/api/endpoints/quests.py) (Quest endpoints), [`backend/database/database.py`](https://github.com/jack26-bit/iko/blob/main/backend/database/database.py) (SQLAlchemy database), [`backend/api/endpoints/users.py`](https://github.com/jack26-bit/iko/blob/main/backend/api/endpoints/users.py) (User endpoints), [`backend/main.py`](https://github.com/jack26-bit/iko/blob/main/backend/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_app["FastAPI application<br/>[main.py]"]
end

subgraph group_identity["User and identity"]
  node_user_routes["User endpoints<br/>[users.py]"]
  node_auth["Password auth<br/>[auth.py]"]
  node_user_access["Current user dependency<br/>[deps.py]"]
  node_user_schema["User schemas<br/>[user.py]"]
end

subgraph group_quest["Quest progression"]
  node_quest_routes["Quest endpoints<br/>[quests.py]"]
  node_quest_schema["Quest schemas<br/>[quest.py]"]
  node_rpg["XP and streak engine<br/>[rpg_engine.py]"]
  node_documented_features["Other documented game features"]
end

subgraph group_state["Domain state"]
  node_user_model["User model<br/>[user.py]"]
  node_quest_model["Quest model<br/>[quest.py]"]
  node_database[("SQLAlchemy database<br/>[database.py]")]
end

node_client(("Mobile app user"))

node_client -.->|"sends requests"| node_app
node_app -->|"registers routes"| node_user_routes
node_app -->|"registers routes"| node_quest_routes
node_app -->|"initializes schema"| node_database
node_user_routes -->|"hashes credentials"| node_auth
node_user_routes -->|"resolves profile"| node_user_access
node_user_routes -->|"validates responses"| node_user_schema
node_user_routes -->|"queries and updates"| node_database
node_user_access -->|"opens session"| node_database
node_user_access -->|"loads user"| node_user_model
node_quest_routes -->|"resolves user"| node_user_access
node_quest_routes -->|"validates payloads"| node_quest_schema
node_quest_routes -->|"queries and writes"| node_quest_model
node_quest_routes -->|"updates user"| node_user_model
node_quest_routes -->|"awards progression"| node_rpg
node_quest_routes -->|"uses session"| node_database
node_rpg -->|"changes RPG state"| node_user_model
node_rpg -->|"commits updates"| node_database
node_quest_model -->|"uses ORM base"| node_database
node_user_model -->|"uses ORM base"| node_database
node_quest_schema -->|"uses difficulty type"| node_quest_model

click node_app "https://github.com/jack26-bit/iko/blob/main/backend/main.py"
click node_user_routes "https://github.com/jack26-bit/iko/blob/main/backend/api/endpoints/users.py"
click node_auth "https://github.com/jack26-bit/iko/blob/main/backend/services/auth.py"
click node_user_access "https://github.com/jack26-bit/iko/blob/main/backend/api/deps.py"
click node_user_schema "https://github.com/jack26-bit/iko/blob/main/backend/schemas/user.py"
click node_quest_routes "https://github.com/jack26-bit/iko/blob/main/backend/api/endpoints/quests.py"
click node_quest_schema "https://github.com/jack26-bit/iko/blob/main/backend/schemas/quest.py"
click node_rpg "https://github.com/jack26-bit/iko/blob/main/backend/services/rpg_engine.py"
click node_documented_features "https://github.com/jack26-bit/iko/tree/main/backend"
click node_user_model "https://github.com/jack26-bit/iko/blob/main/backend/models/user.py"
click node_quest_model "https://github.com/jack26-bit/iko/blob/main/backend/models/quest.py"
click node_database "https://github.com/jack26-bit/iko/blob/main/backend/database/database.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_client toneBlue
class node_user_routes,node_auth,node_user_access,node_user_schema toneAmber
class node_quest_routes,node_quest_schema,node_rpg,node_documented_features toneMint
class node_user_model,node_quest_model,node_database toneRose
```

## Components

### API runtime

- [FastAPI application](https://github.com/jack26-bit/iko/blob/main/backend/main.py): `backend/main.py`

### User and identity

- [User endpoints](https://github.com/jack26-bit/iko/blob/main/backend/api/endpoints/users.py): `backend/api/endpoints/users.py`
- [Password auth](https://github.com/jack26-bit/iko/blob/main/backend/services/auth.py): `backend/services/auth.py`
- [Current user dependency](https://github.com/jack26-bit/iko/blob/main/backend/api/deps.py): `backend/api/deps.py`
- [User schemas](https://github.com/jack26-bit/iko/blob/main/backend/schemas/user.py): `backend/schemas/user.py`

### Quest progression

- [Quest endpoints](https://github.com/jack26-bit/iko/blob/main/backend/api/endpoints/quests.py): `backend/api/endpoints/quests.py`
- [Quest schemas](https://github.com/jack26-bit/iko/blob/main/backend/schemas/quest.py): `backend/schemas/quest.py`
- [XP and streak engine](https://github.com/jack26-bit/iko/blob/main/backend/services/rpg_engine.py): `backend/services/rpg_engine.py`
- [Other documented game features](https://github.com/jack26-bit/iko/tree/main/backend): `backend`

### Domain state

- [User model](https://github.com/jack26-bit/iko/blob/main/backend/models/user.py): `backend/models/user.py`
- [Quest model](https://github.com/jack26-bit/iko/blob/main/backend/models/quest.py): `backend/models/quest.py`
- [SQLAlchemy database](https://github.com/jack26-bit/iko/blob/main/backend/database/database.py): `backend/database/database.py`

### Other components

- **Mobile app user**

## Connections

- Mobile app user → FastAPI application: sends requests
- FastAPI application → User endpoints: registers routes (evidence: `backend/main.py`)
- FastAPI application → Quest endpoints: registers routes (evidence: `backend/main.py`)
- FastAPI application → SQLAlchemy database: initializes schema (evidence: `backend/main.py`)
- User endpoints → Password auth: hashes credentials (evidence: `backend/api/endpoints/users.py`)
- User endpoints → Current user dependency: resolves profile (evidence: `backend/api/endpoints/users.py`)
- User endpoints → User schemas: validates responses (evidence: `backend/api/endpoints/users.py`)
- User endpoints → SQLAlchemy database: queries and updates (evidence: `backend/api/endpoints/users.py`)
- Current user dependency → SQLAlchemy database: opens session (evidence: `backend/api/deps.py`)
- Current user dependency → User model: loads user (evidence: `backend/api/deps.py`)
- Quest endpoints → Current user dependency: resolves user (evidence: `backend/api/endpoints/quests.py`)
- Quest endpoints → Quest schemas: validates payloads (evidence: `backend/api/endpoints/quests.py`)
- Quest endpoints → Quest model: queries and writes (evidence: `backend/api/endpoints/quests.py`)
- Quest endpoints → User model: updates user (evidence: `backend/api/endpoints/quests.py`)
- Quest endpoints → XP and streak engine: awards progression (evidence: `backend/api/endpoints/quests.py`)
- Quest endpoints → SQLAlchemy database: uses session (evidence: `backend/api/endpoints/quests.py`)
- XP and streak engine → User model: changes RPG state (evidence: `backend/services/rpg_engine.py`)
- XP and streak engine → SQLAlchemy database: commits updates (evidence: `backend/services/rpg_engine.py`)
- Quest model → SQLAlchemy database: uses ORM base (evidence: `backend/models/quest.py`)
- User model → SQLAlchemy database: uses ORM base (evidence: `backend/models/user.py`)
- Quest schemas → Quest model: uses difficulty type (evidence: `backend/schemas/quest.py`)
