# clive-bixby/kakurega architecture

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

- Interactive diagram: https://gitdiagram.com/clive-bixby/kakurega
- Repository: https://github.com/clive-bixby/kakurega

## Overview

#### Purpose and Shape
Kakurega is a book-library application with a React/Vite frontend and a Python backend API. The implemented backend is currently a thin service skeleton exposing health status; the frontend already defines the main product surfaces: dashboard, library, search, add-book, insights, and settings.

Key entry points:
- Frontend bootstrap: `frontend/src/main.tsx`, `frontend/src/App.tsx`
- Backend ASGI application: `backend/app/main.py`
- Versioned API composition: `backend/app/api/v1/router.py`

#### Frontend Application Shell and Navigation
The frontend is a TypeScript single-page application. `App.tsx` is the application-level composition point, while `AppLayout.tsx` provides the shared frame around feature pages. This layout boundary should own persistent navigation and shared chrome, leaving pages responsible for feature-specific content.

Paths:
- `frontend/src/App.tsx`
- `frontend/src/layouts/AppLayout.tsx`
- `frontend/src/styles.css`

#### Product Feature Pages
The UI is organized as route/page-level modules for the core book-management workflows. These are currently the clearest representation of product capabilities and should become the primary consumers of backend APIs.

Feature boundaries:
- Book collection browsing: `frontend/src/pages/LibraryPage.tsx`
- Book discovery: `frontend/src/pages/SearchPage.tsx`
- Book creation/import flow: `frontend/src/pages/AddBookPage.tsx`
- Summary and analytics views: `frontend/src/pages/DashboardPage.tsx`, `frontend/src/pages/InsightsPage.tsx`
- User/application preferences: `frontend/src/pages/SettingsPage.tsx`

Design prototypes for these flows are preserved separately under `design/stitch/`, rather than being runtime code.

#### Backend API Layer
The backend uses a versioned API structure, with route modules aggregated by a v1 router and mounted from the application entry point. The sole implemented endpoint is health, with a corresponding response schema and test. This establishes the intended API pattern: route handler → schema → service/repository/model layers as needed.

Paths:
- `backend/app/main.py`
- `backend/app/api/v1/router.py`
- `backend/app/api/v1/routes/health.py`
- `backend/app/schemas/health.py`

#### Domain and Persistence Expansion Boundaries
The backend reserves explicit packages for domain models, persistence repositories, business services, utilities, and background workers. These are architectural seams, but are presently empty; book records, search integration, analytics computation, and asynchronous imports have not yet been implemented in this tree.

Paths:
- `backend/app/models/__init__.py`
- `backend/app/repositories/__init__.py`
- `backend/app/services/__init__.py`
- `backend/app/workers/__init__.py`

Documentation indicates planned API, database, and system architecture decisions:
- `docs/API.md`
- `docs/DATABASE.md`
- `docs/SYSTEM_ARCHITECTURE.md`

#### Runtime, Configuration, and Delivery Boundaries
The frontend runs through Vite (`frontend/vite.config.ts`) and packages dependencies via npm. The backend is a Python package defined by `backend/pyproject.toml`; environment-driven configuration is centralized in `backend/app/core/config.py`, with expected variables documented in `backend/.env.example`.

No concrete database driver, external API client, queue implementation, or deployed infrastructure is evident from the supplied tree. Any such integration should enter through configuration plus the repository/service/worker boundaries, rather than route handlers or frontend pages directly.

Main entry points: [`frontend/src/layouts/AppLayout.tsx`](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/layouts/AppLayout.tsx) (Shared app layout), [`frontend/src/App.tsx`](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/App.tsx) (App composition), [`backend/app/main.py`](https://github.com/clive-bixby/kakurega/blob/main/backend/app/main.py) (ASGI application), [`backend/app/api/v1/router.py`](https://github.com/clive-bixby/kakurega/blob/main/backend/app/api/v1/router.py) (v1 API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_frontend_bootstrap(("Frontend bootstrap<br/>React/Vite entry<br/>[main.tsx]"))
  node_app["App composition<br/>React app<br/>[App.tsx]"]
  node_layout["Shared app layout<br/>UI shell<br/>[AppLayout.tsx]"]
  node_library["Library<br/>feature page<br/>[LibraryPage.tsx]"]
  node_search["Search<br/>feature page<br/>[SearchPage.tsx]"]
  node_add_book["Add book<br/>feature page<br/>[AddBookPage.tsx]"]
  node_dashboard["Dashboard<br/>feature page<br/>[DashboardPage.tsx]"]
  node_insights["Insights<br/>feature page<br/>[InsightsPage.tsx]"]
  node_settings["Settings<br/>feature page<br/>[SettingsPage.tsx]"]
end

subgraph group_backend["Backend API"]
  node_api_app["ASGI application<br/>Python API entry<br/>[main.py]"]
  node_v1_router["v1 API router<br/>route composition<br/>[router.py]"]
  node_health_route["Health endpoint<br/>route handler<br/>[health.py]"]
  node_health_schema["Health response<br/>schema<br/>[health.py]"]
  node_config["Environment config<br/>configuration<br/>[config.py]"]
end

subgraph group_expansion["Planned backend seams"]
  node_services["Business services<br/>reserved service layer<br/>[__init__.py]"]
  node_repositories[("Persistence repositories<br/>reserved repository layer<br/>[__init__.py]")]
  node_models["Domain models<br/>reserved domain layer<br/>[__init__.py]"]
  node_workers["Background workers<br/>reserved worker layer<br/>[__init__.py]"]
end

node_frontend_bootstrap -->|"mounts"| node_app
node_app -->|"composes"| node_layout
node_layout -->|"frames"| node_library
node_layout -->|"frames"| node_search
node_layout -->|"frames"| node_add_book
node_layout -->|"frames"| node_dashboard
node_layout -->|"frames"| node_insights
node_layout -->|"frames"| node_settings
node_app -.->|"future API consumer"| node_api_app
node_api_app -->|"mounts"| node_v1_router
node_v1_router -->|"aggregates"| node_health_route
node_health_route -->|"returns"| node_health_schema
node_api_app -->|"reads"| node_config
node_v1_router -.->|"future delegation"| node_services
node_services -.->|"uses"| node_repositories
node_repositories -.->|"persists"| node_models
node_services -.->|"queues imports"| node_workers

click node_frontend_bootstrap "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/main.tsx"
click node_app "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/App.tsx"
click node_layout "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/layouts/AppLayout.tsx"
click node_library "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/LibraryPage.tsx"
click node_search "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/SearchPage.tsx"
click node_add_book "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/AddBookPage.tsx"
click node_dashboard "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_insights "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/InsightsPage.tsx"
click node_settings "https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/SettingsPage.tsx"
click node_api_app "https://github.com/clive-bixby/kakurega/blob/main/backend/app/main.py"
click node_v1_router "https://github.com/clive-bixby/kakurega/blob/main/backend/app/api/v1/router.py"
click node_health_route "https://github.com/clive-bixby/kakurega/blob/main/backend/app/api/v1/routes/health.py"
click node_health_schema "https://github.com/clive-bixby/kakurega/blob/main/backend/app/schemas/health.py"
click node_config "https://github.com/clive-bixby/kakurega/blob/main/backend/app/core/config.py"
click node_services "https://github.com/clive-bixby/kakurega/blob/main/backend/app/services/__init__.py"
click node_repositories "https://github.com/clive-bixby/kakurega/blob/main/backend/app/repositories/__init__.py"
click node_models "https://github.com/clive-bixby/kakurega/blob/main/backend/app/models/__init__.py"
click node_workers "https://github.com/clive-bixby/kakurega/blob/main/backend/app/workers/__init__.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_frontend_bootstrap,node_app,node_layout,node_library,node_search,node_add_book,node_dashboard,node_insights,node_settings toneBlue
class node_api_app,node_v1_router,node_health_route,node_health_schema,node_config toneAmber
class node_services,node_repositories,node_models,node_workers toneMint
```

## Components

### Frontend SPA

- [Frontend bootstrap](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/main.tsx): React/Vite entry · `frontend/src/main.tsx`
- [App composition](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/App.tsx): React app · `frontend/src/App.tsx`
- [Shared app layout](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/layouts/AppLayout.tsx): UI shell · Owns persistent navigation and shared chrome. · `frontend/src/layouts/AppLayout.tsx`
- [Library](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/LibraryPage.tsx): feature page · `frontend/src/pages/LibraryPage.tsx`
- [Search](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/SearchPage.tsx): feature page · `frontend/src/pages/SearchPage.tsx`
- [Add book](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/AddBookPage.tsx): feature page · `frontend/src/pages/AddBookPage.tsx`
- [Dashboard](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/DashboardPage.tsx): feature page · `frontend/src/pages/DashboardPage.tsx`
- [Insights](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/InsightsPage.tsx): feature page · `frontend/src/pages/InsightsPage.tsx`
- [Settings](https://github.com/clive-bixby/kakurega/blob/main/frontend/src/pages/SettingsPage.tsx): feature page · `frontend/src/pages/SettingsPage.tsx`

### Backend API

- [ASGI application](https://github.com/clive-bixby/kakurega/blob/main/backend/app/main.py): Python API entry · `backend/app/main.py`
- [v1 API router](https://github.com/clive-bixby/kakurega/blob/main/backend/app/api/v1/router.py): route composition · `backend/app/api/v1/router.py`
- [Health endpoint](https://github.com/clive-bixby/kakurega/blob/main/backend/app/api/v1/routes/health.py): route handler · The sole implemented API endpoint. · `backend/app/api/v1/routes/health.py`
- [Health response](https://github.com/clive-bixby/kakurega/blob/main/backend/app/schemas/health.py): schema · `backend/app/schemas/health.py`
- [Environment config](https://github.com/clive-bixby/kakurega/blob/main/backend/app/core/config.py): configuration · Centralizes environment-driven backend settings. · `backend/app/core/config.py`

### Planned backend seams

Reserved packages for future book capabilities.

- [Business services](https://github.com/clive-bixby/kakurega/blob/main/backend/app/services/__init__.py): reserved service layer · Future business logic boundary. · `backend/app/services/__init__.py`
- [Persistence repositories](https://github.com/clive-bixby/kakurega/blob/main/backend/app/repositories/__init__.py): reserved repository layer · Future persistence integration boundary. · `backend/app/repositories/__init__.py`
- [Domain models](https://github.com/clive-bixby/kakurega/blob/main/backend/app/models/__init__.py): reserved domain layer · Future book-record domain boundary. · `backend/app/models/__init__.py`
- [Background workers](https://github.com/clive-bixby/kakurega/blob/main/backend/app/workers/__init__.py): reserved worker layer · Future asynchronous import boundary. · `backend/app/workers/__init__.py`

## Connections

- Frontend bootstrap → App composition: mounts
- App composition → Shared app layout: composes
- Shared app layout → Library: frames
- Shared app layout → Search: frames
- Shared app layout → Add book: frames
- Shared app layout → Dashboard: frames
- Shared app layout → Insights: frames
- Shared app layout → Settings: frames
- App composition → ASGI application: future API consumer
- ASGI application → v1 API router: mounts
- v1 API router → Health endpoint: aggregates
- Health endpoint → Health response: returns
- ASGI application → Environment config: reads
- v1 API router → Business services: future delegation
- Business services → Persistence repositories: uses
- Persistence repositories → Domain models: persists
- Business services → Background workers: queues imports