clive-bixby/kakurega

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.