# 5945ggh/folio-j architecture

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

- Interactive diagram: https://gitdiagram.com/5945ggh/folio-j
- Repository: https://github.com/5945ggh/folio-j

## Overview

Folio-J is a local Japanese-reading app for managing sources and manually entered excerpts, discussing excerpts with background model-powered chat, and maintaining learner/provider settings. The main workflow is to create a source and excerpt, open its reading workspace, then submit questions to a durable chat job and revisit its history. The backend also exposes analysis management and job-agent analysis tools; independent explanations and accumulated learning entries are described as future work. Relationships for unsampled route and frontend modules are included only where documented or indexed; uncertain wiring is omitted.

Main entry points: [`backend/src/app/main.py`](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/main.py) (ASGI app), [`frontend/src/App.tsx`](https://github.com/5945ggh/folio-j/blob/main/frontend/src/App.tsx) (App routes), [`backend/src/app/services/chat.py`](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/chat.py) (Chat lifecycle), [`backend/src/app/services/settings.py`](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/settings.py) (Provider and learning settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Reading interface"]
  node_app_ui["App routes<br/>[App.tsx]"]
  node_source_ui["Source pages<br/>[SourcePages.tsx]"]
  node_segment_ui["Excerpt workspace<br/>[SegmentPage.tsx]"]
  node_chat_ui["Discussion workbench<br/>[Workbench.tsx]"]
  node_settings_ui["Settings pages<br/>[SettingsPage.tsx]"]
  node_content_api["Source API client<br/>[content.ts]"]
  node_chat_api["Chat API client<br/>[api.ts]"]
  node_settings_api_ui["Settings API client<br/>[api.ts]"]
end

subgraph group_http["API and domain"]
  node_app_server["ASGI app<br/>[main.py]"]
  node_sources_routes["Source routes<br/>[sources.py]"]
  node_settings_routes["Settings routes<br/>[settings.py]"]
  node_chat_routes["Chat routes<br/>[chat.py]"]
  node_analysis_routes["Analysis routes<br/>[analyses.py]"]
  node_source_domain["Source management<br/>[sources.py]"]
  node_chat_domain["Chat lifecycle<br/>[chat.py]"]
  node_context["Prompt context<br/>[context.py]"]
  node_analysis_domain["Analysis management<br/>[analyses.py]"]
  node_settings_domain["Provider and learning settings<br/>[settings.py]"]
end

subgraph group_jobs["Background work"]
  node_worker["Job supervisor<br/>[runtime.py]"]
  node_agent["Chat agent<br/>[agent.py]"]
  node_llm["Model adapters<br/>[adapters.py]"]
end

subgraph group_storage["Persistence and models"]
  node_db_engine[("SQLite engine<br/>[db.py]")]
  node_domain_models[("Source and settings models<br/>[models.py]")]
  node_chat_models[("Chat job models<br/>[chat_models.py]")]
  node_settings_models[("Settings models<br/>[settings_models.py]")]
end

node_reader(("Reader"))
node_model_provider{{"Model provider"}}

node_reader -->|"uses"| node_app_ui
node_app_ui -->|"routes to"| node_source_ui
node_app_ui -->|"routes to"| node_segment_ui
node_app_ui -->|"routes to"| node_settings_ui
node_source_ui -.->|"requests"| node_content_api
node_segment_ui -->|"renders"| node_chat_ui
node_segment_ui -->|"requests"| node_content_api
node_chat_ui -->|"requests"| node_chat_api
node_settings_ui -.->|"requests"| node_settings_api_ui
node_content_api -->|"HTTP requests"| node_app_server
node_chat_api -->|"HTTP requests"| node_app_server
node_settings_api_ui -->|"HTTP requests"| node_app_server
node_app_server -->|"registers"| node_sources_routes
node_app_server -->|"registers"| node_settings_routes
node_app_server -->|"registers"| node_chat_routes
node_app_server -->|"registers"| node_analysis_routes
node_sources_routes -->|"delegates"| node_source_domain
node_settings_routes -->|"delegates"| node_settings_domain
node_chat_routes -.->|"delegates"| node_chat_domain
node_chat_domain -->|"builds context"| node_context
node_chat_domain -->|"loads settings"| node_settings_domain
node_app_server -->|"starts worker"| node_worker
node_worker -->|"runs jobs"| node_agent
node_agent -->|"calls model"| node_llm
node_agent -->|"creates analysis"| node_analysis_domain
node_settings_domain -->|"verifies models"| node_llm
node_llm -->|"calls"| node_model_provider
node_app_server -.->|"creates engine"| node_db_engine
node_sources_routes -->|"uses sessions"| node_db_engine
node_settings_routes -->|"uses sessions"| node_db_engine
node_source_domain -->|"manages records"| node_domain_models
node_chat_domain -->|"manages history"| node_chat_models
node_settings_domain -->|"manages settings"| node_settings_models

click node_app_ui "https://github.com/5945ggh/folio-j/blob/main/frontend/src/App.tsx"
click node_source_ui "https://github.com/5945ggh/folio-j/blob/main/frontend/src/SourcePages.tsx"
click node_segment_ui "https://github.com/5945ggh/folio-j/blob/main/frontend/src/SegmentPage.tsx"
click node_chat_ui "https://github.com/5945ggh/folio-j/blob/main/frontend/src/chat/Workbench.tsx"
click node_settings_ui "https://github.com/5945ggh/folio-j/blob/main/frontend/src/settings/SettingsPage.tsx"
click node_content_api "https://github.com/5945ggh/folio-j/blob/main/frontend/src/content.ts"
click node_chat_api "https://github.com/5945ggh/folio-j/blob/main/frontend/src/chat/api.ts"
click node_settings_api_ui "https://github.com/5945ggh/folio-j/blob/main/frontend/src/settings/api.ts"
click node_app_server "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/main.py"
click node_sources_routes "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/api/sources.py"
click node_settings_routes "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/api/settings.py"
click node_chat_routes "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/api/chat.py"
click node_analysis_routes "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/api/analyses.py"
click node_source_domain "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/sources.py"
click node_chat_domain "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/chat.py"
click node_context "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/context.py"
click node_analysis_domain "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/analyses.py"
click node_settings_domain "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/settings.py"
click node_worker "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/jobs/runtime.py"
click node_agent "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/jobs/agent.py"
click node_llm "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/llm/adapters.py"
click node_db_engine "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/db.py"
click node_domain_models "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/models.py"
click node_chat_models "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/chat_models.py"
click node_settings_models "https://github.com/5945ggh/folio-j/blob/main/backend/src/app/settings_models.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_ui,node_source_ui,node_segment_ui,node_chat_ui,node_settings_ui,node_content_api,node_chat_api,node_settings_api_ui toneBlue
class node_app_server,node_sources_routes,node_settings_routes,node_chat_routes,node_analysis_routes,node_source_domain,node_chat_domain,node_context,node_analysis_domain,node_settings_domain toneAmber
class node_worker,node_agent,node_llm toneMint
class node_db_engine,node_domain_models,node_chat_models,node_settings_models toneRose
class node_reader,node_model_provider toneIndigo
```

## Components

### Reading interface

- [App routes](https://github.com/5945ggh/folio-j/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Source pages](https://github.com/5945ggh/folio-j/blob/main/frontend/src/SourcePages.tsx): `frontend/src/SourcePages.tsx`
- [Excerpt workspace](https://github.com/5945ggh/folio-j/blob/main/frontend/src/SegmentPage.tsx): `frontend/src/SegmentPage.tsx`
- [Discussion workbench](https://github.com/5945ggh/folio-j/blob/main/frontend/src/chat/Workbench.tsx): `frontend/src/chat/Workbench.tsx`
- [Settings pages](https://github.com/5945ggh/folio-j/blob/main/frontend/src/settings/SettingsPage.tsx): `frontend/src/settings/SettingsPage.tsx`
- [Source API client](https://github.com/5945ggh/folio-j/blob/main/frontend/src/content.ts): `frontend/src/content.ts`
- [Chat API client](https://github.com/5945ggh/folio-j/blob/main/frontend/src/chat/api.ts): `frontend/src/chat/api.ts`
- [Settings API client](https://github.com/5945ggh/folio-j/blob/main/frontend/src/settings/api.ts): `frontend/src/settings/api.ts`

### API and domain

- [ASGI app](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/main.py): `backend/src/app/main.py`
- [Source routes](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/api/sources.py): `backend/src/app/api/sources.py`
- [Settings routes](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/api/settings.py): `backend/src/app/api/settings.py`
- [Chat routes](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/api/chat.py): `backend/src/app/api/chat.py`
- [Analysis routes](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/api/analyses.py): `backend/src/app/api/analyses.py`
- [Source management](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/sources.py): `backend/src/app/services/sources.py`
- [Chat lifecycle](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/chat.py): `backend/src/app/services/chat.py`
- [Prompt context](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/context.py): `backend/src/app/services/context.py`
- [Analysis management](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/analyses.py): `backend/src/app/services/analyses.py`
- [Provider and learning settings](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/services/settings.py): `backend/src/app/services/settings.py`

### Background work

- [Job supervisor](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/jobs/runtime.py): `backend/src/app/jobs/runtime.py`
- [Chat agent](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/jobs/agent.py): `backend/src/app/jobs/agent.py`
- [Model adapters](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/llm/adapters.py): `backend/src/app/llm/adapters.py`

### Persistence and models

- [SQLite engine](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/db.py): `backend/src/app/db.py`
- [Source and settings models](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/models.py): `backend/src/app/models.py`
- [Chat job models](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/chat_models.py): `backend/src/app/chat_models.py`
- [Settings models](https://github.com/5945ggh/folio-j/blob/main/backend/src/app/settings_models.py): `backend/src/app/settings_models.py`

### Other components

- **Reader**
- **Model provider**

## Connections

- Reader → App routes: uses (evidence: `README.md`)
- App routes → Source pages: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Excerpt workspace: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Settings pages: routes to (evidence: `frontend/src/App.tsx`)
- Source pages → Source API client: requests
- Excerpt workspace → Discussion workbench: renders (evidence: `frontend/src/SegmentPage.tsx`)
- Excerpt workspace → Source API client: requests (evidence: `frontend/src/SegmentPage.tsx`)
- Discussion workbench → Chat API client: requests (evidence: `frontend/src/chat/Workbench.tsx`)
- Settings pages → Settings API client: requests
- Source API client → ASGI app: HTTP requests (evidence: `frontend/src/content.ts`)
- Chat API client → ASGI app: HTTP requests (evidence: `frontend/src/chat/api.ts`)
- Settings API client → ASGI app: HTTP requests (evidence: `frontend/src/settings/api.ts`)
- ASGI app → Source routes: registers (evidence: `backend/src/app/main.py`)
- ASGI app → Settings routes: registers (evidence: `backend/src/app/main.py`)
- ASGI app → Chat routes: registers (evidence: `backend/src/app/main.py`)
- ASGI app → Analysis routes: registers (evidence: `backend/src/app/main.py`)
- Source routes → Source management: delegates (evidence: `backend/src/app/api/sources.py`)
- Settings routes → Provider and learning settings: delegates (evidence: `backend/src/app/api/settings.py`)
- Chat routes → Chat lifecycle: delegates
- Chat lifecycle → Prompt context: builds context (evidence: `backend/src/app/services/chat.py`)
- Chat lifecycle → Provider and learning settings: loads settings (evidence: `backend/src/app/services/chat.py`)
- ASGI app → Job supervisor: starts worker (evidence: `backend/src/app/main.py`)
- Job supervisor → Chat agent: runs jobs (evidence: `backend/src/app/jobs/runtime.py`)
- Chat agent → Model adapters: calls model (evidence: `backend/src/app/jobs/agent.py`)
- Chat agent → Analysis management: creates analysis (evidence: `backend/src/app/jobs/agent.py`)
- Provider and learning settings → Model adapters: verifies models (evidence: `backend/src/app/services/settings.py`)
- Model adapters → Model provider: calls (evidence: `backend/src/app/llm/adapters.py`)
- ASGI app → SQLite engine: creates engine (evidence: `backend/src/app/main.py`)
- Source routes → SQLite engine: uses sessions (evidence: `backend/src/app/api/sources.py`)
- Settings routes → SQLite engine: uses sessions (evidence: `backend/src/app/api/settings.py`)
- Source management → Source and settings models: manages records (evidence: `backend/src/app/services/analyses.py`)
- Chat lifecycle → Chat job models: manages history (evidence: `backend/src/app/services/chat.py`)
- Provider and learning settings → Settings models: manages settings (evidence: `backend/src/app/services/settings.py`)
