# shutootaki/bookwith architecture

> Architecture diagram of the GitHub repository shutootaki/bookwith, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shutootaki/bookwith
- Repository: https://github.com/shutootaki/bookwith

## Overview

##### Project Type and Purpose
- This is a full-stack, monorepo web platform called **BookWith**.
- Frontend: a React/Next.js reader application (“apps/reader”).
- Backend: a Python service (FastAPI-style) serving REST endpoints (“apps/api”).
- Packages: shared libraries (e.g., epubjs rendering engine, Tailwind extensions).
- Purpose: deliver an AI-powered e-book reading experience with annotations, chat, and semantic search.

##### File Structure
- Top level is a **pnpm/Turbo** monorepo:
- apps/api – the Python backend (domain-driven, layered architecture with config, domain, infrastructure, usecases, presentation).
- apps/reader – the Next.js frontend (UI components, hooks, API client, styles, workers).
- packages – reusable modules (epubjs renderer, Tailwind design tokens, internal utilities).
- supabase – database migrations/auth config.
- CI/CD workflows for frontend and backend in `.github/workflows`.
- Shared linting, formatting, and pre-commit hooks.

##### README for Additional Insights
- Describes AI Reading Assistant, Multi-Layer Memory (short, mid, long-term), Smart Annotation, Semantic Search.
- Indicates external dependencies: GPT-4/OpenAI, Google Cloud Storage, Postgres, vector database, Supabase auth.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Device
    User["User Device\n(Browser)"]:::external

    %% Frontend Layer
    subgraph "Frontend (Next.js Reader)" 
        direction TB
        Pages["Next.js Pages\n(apps/reader/src/pages)"]:::frontend
        Components["UI Components\n(apps/reader/src/components)"]:::frontend
        Hooks["Hooks (SWR, state)\n(apps/reader/src/hooks)"]:::frontend
        APIClient["API Client\n(apps/reader/src/lib/apiHandler)"]:::frontend
        Styles["Styles & Tailwind\n(tailwind.config.cjs,\nstyles.css)"]:::frontend
        Workers["Web Worker\n(importWorker.ts)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)" 
        direction TB
        APIMain["API Gateway\n(main.py)"]:::presentation
        subgraph "Presentation Layer"
            direction TB
            Routes["Routes Definitions\n(routes.py)"]:::presentation
            Handlers["Route Handlers\n(handlers/)"]:::presentation
            Schemas["Pydantic Schemas\n(schemas/)"]:::presentation
            Errors["Error Handlers\n(error_messages)"]:::presentation
        end
        subgraph "Use Case Layer"
            direction TB
            BookUC["UseCase: Book\n(usecase/book)"]:::usecase
            ChatUC["UseCase: Chat\n(usecase/chat)"]:::usecase
            MessageUC["UseCase: Message\n(usecase/message)"]:::usecase
            AnnotationUC["UseCase: Annotation\n(usecase/annotation)"]:::usecase
        end
        subgraph "Domain Layer"
            direction TB
            BookDomain["Domain: Book\n(domain/book)"]:::domain
            ChatDomain["Domain: Chat\n(domain/chat)"]:::domain
            MessageDomain["Domain: Message\n(domain/message)"]:::domain
            AnnotationDomain["Domain: Annotation\n(domain/annotation)"]:::domain
        end
        subgraph "Infrastructure Layer"
            direction TB
            DI["Dependency Injection\n(injection.py)"]:::infra
            GCS["GCS Storage\n(gcs.py)"]:::infra
            InMem["In-Memory Service\n(memory_service.py)"]:::infra
            Vector["Vector Store\n(memory_vector_store.py)"]:::infra
            VectorUtil["Vector Utils\n(vector.py)"]:::infra
            subgraph "Postgres Repositories"
                direction TB
                BookRepo["Book Repo\n(book_repository.py)"]:::infra
                ChatRepo["Chat Repo\n(chat_repository.py)"]:::infra
                MessageRepo["Message Repo\n(message_repository.py)"]:::infra
                AnnotationRepo["Annotation Repo\n(annotation_repository.py)"]:::infra
                DBUtil["DB Utilities\n(db_util.py)"]:::infra
            end
        end
        subgraph "Config & DB"
            direction TB
            AppConfig["App Config\n(app_config.py)"]:::infra
            DBConfig["DB & Migrations\n(db.py, seed.py)"]:::infra
            EnvExample[".env.example"]:::infra
        end
    end

    %% Shared Packages
    subgraph "Shared Packages"
        direction TB
        EPUBJS["EPUB Renderer\n(packages/epubjs)"]:::packages
        TailwindPkg["Tailwind Tokens\n(packages/tailwind)"]:::packages
        InternalUtils["Internal Utils\n(packages/internal)"]:::packages
    end

    %% CI/CD & Supabase
    CIBackend["Backend CI\n(.github/workflows/backend-ci.yml)"]:::infra
    CIFrontend["Frontend CI\n(.github/workflows/frontend-ci.yml)"]:::infra
    SupabaseCfg["Supabase Config\n(supabase/config.toml)"]:::infra

    %% External Services
    subgraph "External Services"
        direction TB
        Postgres["Postgres DB"]:::external
        VectorStoreExt["Vector DB\n(Pinecone or PG)"]:::external
        GCSBucket["Google Cloud Storage"]:::external
        OpenAI["OpenAI GPT-4 API"]:::external
        SupabaseAuth["Supabase Auth"]:::external
    end

    %% Data Flows
    User -->|Uses| Pages
    Pages -->|Renders| Components
    Components -->|Uses| Hooks
    Components -->|Fetches| APIClient
    APIClient -->|Calls| APIMain
    Workers -->|Loads ePub| Components
    Styles -->|Styling| Components

    APIMain -->|Routes to| Routes
    Routes -->|Executes| Handlers
    Handlers -->|Validates| Schemas
    Handlers -->|Handles Errors| Errors
    Handlers -->|Calls| BookUC
    Handlers -->|Calls| ChatUC
    Handlers -->|Calls| MessageUC
    Handlers -->|Calls| AnnotationUC

    BookUC -->|Uses| BookDomain
    ChatUC -->|Uses| ChatDomain
    MessageUC -->|Uses| MessageDomain
    AnnotationUC -->|Uses| AnnotationDomain

    BookDomain -->|Persists/Retrieves| BookRepo
    ChatDomain -->|Persists/Retrieves| ChatRepo
    MessageDomain -->|Persists/Retrieves| MessageRepo
    AnnotationDomain -->|Persists/Retrieves| AnnotationRepo

    BookUC -->|Loads ePub| GCS
    ChatUC -->|Calls| OpenAI
    ChatUC -->|Queries| Vector
    ChatUC -->|Queries| VectorStoreExt
    ChatUC -->|Stores| InMem
    ChatUC -->|Stores| BookRepo

    DI -->|Injects| Handlers
    DBUtil -->|Manages| Postgres
    DBConfig -->|Migrations| Postgres
    SupabaseCfg -->|Auth| SupabaseAuth

    EPUBJS -->|Used by| Components
    TailwindPkg -->|Used by| Styles
    InternalUtils -->|Shared| Hooks

    CIBackend -->|Tests/Builds| APIMain
    CIFrontend -->|Tests/Builds| Pages

    %% Click Events
    click Pages "https://github.com/shutootaki/bookwith/tree/main/apps/reader/src/pages"
    click Components "https://github.com/shutootaki/bookwith/tree/main/apps/reader/src/components"
    click Hooks "https://github.com/shutootaki/bookwith/tree/main/apps/reader/src/hooks"
    click APIClient "https://github.com/shutootaki/bookwith/tree/main/apps/reader/src/lib/apiHandler"
    click Styles "https://github.com/shutootaki/bookwith/blob/main/apps/reader/tailwind.config.cjs"
    click Styles "https://github.com/shutootaki/bookwith/blob/main/apps/reader/src/pages/styles.css"
    click Workers "https://github.com/shutootaki/bookwith/blob/main/apps/reader/src/workers/importWorker.ts"
    click APIMain "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/main.py"
    click Routes "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/presentation/api/routes.py"
    click Handlers "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/presentation/api/handlers"
    click Schemas "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/presentation/api/schemas"
    click Errors "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/presentation/api/error_messages"
    click BookUC "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/usecase/book"
    click ChatUC "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/usecase/chat"
    click MessageUC "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/usecase/message"
    click AnnotationUC "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/usecase/annotation"
    click BookDomain "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/domain/book"
    click ChatDomain "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/domain/chat"
    click MessageDomain "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/domain/message"
    click AnnotationDomain "https://github.com/shutootaki/bookwith/tree/main/apps/api/src/domain/annotation"
    click DI "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/di/injection.py"
    click GCS "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/external/gcs.py"
    click InMem "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/memory/memory_service.py"
    click Vector "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/memory/memory_vector_store.py"
    click VectorUtil "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/vector.py"
    click BookRepo "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/postgres/book/book_repository.py"
    click ChatRepo "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/postgres/chat/chat_repository.py"
    click MessageRepo "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/postgres/message/message_repository.py"
    click AnnotationRepo "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/postgres/annotation/annotation_repository.py"
    click DBUtil "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/infrastructure/postgres/db_util.py"
    click AppConfig "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/config/app_config.py"
    click DBConfig "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/config/db.py"
    click EnvExample "https://github.com/shutootaki/bookwith/blob/main/apps/api/src/config/.env.example"
    click EPUBJS "https://github.com/shutootaki/bookwith/tree/main/packages/epubjs"
    click TailwindPkg "https://github.com/shutootaki/bookwith/tree/main/packages/tailwind"
    click InternalUtils "https://github.com/shutootaki/bookwith/tree/main/packages/internal"
    click CIBackend "https://github.com/shutootaki/bookwith/blob/main/.github/workflows/backend-ci.yml"
    click CIFrontend "https://github.com/shutootaki/bookwith/blob/main/.github/workflows/frontend-ci.yml"
    click SupabaseCfg "https://github.com/shutootaki/bookwith/blob/main/supabase/config.toml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef presentation fill:#E6F4EA,stroke:#2c662d,stroke-width:1px
    classDef usecase fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef domain fill:#FFF4E5,stroke:#b36b00,stroke-width:1px
    classDef infra fill:#F5E6FF,stroke:#5e2ca5,stroke-width:1px
    classDef packages fill:#FFF0F5,stroke:#c71585,stroke-width:1px
    classDef external fill:#FFEFE0,stroke:#d65a00,stroke-width:1px
```
