# aniketsandhanwootz-wq/pdf-markbook architecture

> Architecture diagram of the GitHub repository aniketsandhanwootz-wq/pdf-markbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aniketsandhanwootz-wq/pdf-markbook
- Repository: https://github.com/aniketsandhanwootz-wq/pdf-markbook

## Overview

##### Project Type and Purpose
- This is a full-stack, monorepo web application for annotating and reviewing PDF documents.
- It comprises two Next.js front-end applications (“editor” and “viewer”), a Python-based REST API back end, a relational data store (SQLite by default, with adapters for Postgres, Sheets, etc.), and SQL migration scripts for infra.

##### High-Level Architecture
- Frontends (apps/editor, apps/viewer)
- Next.js + React + TypeScript
- Canvas-based PDF rendering & search components
- Communicate with the back end via HTTP/REST
- API Service (services/api)
- Python (FastAPI or Flask style)
- Routers define REST endpoints (documents, pages, marks, reports, etc.)
- Core business logic (email, PDF report generation, validation)
- Adapters layer (SQLite, Postgres, Sheets, JSON) abstracts the data source
- Models & Pydantic schemas for data validation & serialization
- Database
- Default: local SQLite (services/api/data/markbook.db, marks.db)
- Infra/sql contains migration scripts (001_init.sql) for initializing schema
- Deployment/Infra
- Dockerfile for API service
- render.yaml for Render.com deployment
- package.json at root orchestrates mono-repo dependencies

##### Main Components & Interactions
- Editor Frontend
- UI component tree under apps/editor/components
- lib/pdf.ts for client-side PDF parsing/rendering
- Fetches and posts annotations and mark sets to API
- Viewer Frontend
- Similar components under apps/viewer/components + a Web Worker for search (search.worker.ts)
- Reads existing annotations and facilitates review workflows
- API Gateway
- Entry point: services/api/main.py
- Routes → Core → Adapters → DB
- Data Persistence
- Adapters selected at runtime via settings.py
- Core modules call adapter interfaces (e.g., .load_groups(), .save_mark())
- External Services
- Email sender (SMTP)
- Optionally Google Sheets via sheets adapter
- PDF/Excel report generators for exporting results

##### Architectural Patterns & Principles
- Layered architecture: Presentation (frontends) → Application (API routers) → Domain (core business logic) → Infrastructure (adapters → DB).
- Adapter (Port & Adapter) pattern for pluggable persistence.
- Separation of concerns: Frontend/Backend, Business logic vs. I/O, Data models vs. Schemas.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Applications
    subgraph "Frontend Layer"
        direction TB
        EditorApp["Editor App"]:::frontend
        EditorComponents["Editor Components"]:::frontend
        EditorPDF["PDF Library"]:::frontend
        ViewerApp["Viewer App"]:::frontend
        ViewerComponents["Viewer Components"]:::frontend
        ViewerPDF["PDF Library"]:::frontend
        ViewerWorker["Search Web Worker"]:::frontend
    end

    %% API Service with layers
    subgraph "API Service" 
        direction TB
        APIEntry["main.py"]:::api
        subgraph "Routers" 
            Routers["API Routers"]:::routers
        end
        subgraph "Core Business Logic"
            Core["Core Logic"]:::core
        end
        subgraph "Persistence Adapters"
            direction TB
            Adapters["Adapters"]:::adapters
            SQLite["SQLite Adapter"]:::adapters
            Postgres["Postgres Adapter"]:::adapters
            SheetsAdapter["Sheets Adapter"]:::adapters
            JSONAdapter["JSON Adapter"]:::adapters
        end
        Models["Data Models"]:::model
        Schemas["Pydantic Schemas"]:::model
        Settings["settings.py"]:::api
    end

    %% Database
    Database[(SQLite Databases)]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        Email["SMTP Email"]:::external
        Sheets["Google Sheets"]:::external
        PDFGen["PDF/Excel Generator"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Migrations["001_init.sql"]:::infra
        Dockerfile["Dockerfile"]:::infra
        Requirements["requirements.txt"]:::infra
        RootPackage["package.json"]:::infra
        RenderConfig["render.yaml"]:::infra
    end

    %% Connections
    EditorApp -->|"HTTP GET/POST /documents, /marks"| Routers
    EditorComponents --> EditorApp
    EditorPDF --> EditorApp
    ViewerApp -->|"HTTP GET /review"| Routers
    ViewerComponents --> ViewerApp
    ViewerPDF --> ViewerApp
    ViewerWorker --> ViewerApp

    APIEntry --> Routers
    Routers --> Core
    Core --> Adapters
    Adapters --> SQLite
    Adapters --> Postgres
    Adapters --> SheetsAdapter
    Adapters --> JSONAdapter
    Routers --> Models
    Routers --> Schemas
    Core --> Email
    Core --> Sheets
    Core --> PDFGen

    SQLite --> Database

    Settings --> Adapters
    Settings --> Core

    Migrations --> Database
    Dockerfile --> APIEntry
    Requirements --> APIEntry
    RootPackage --> EditorApp
    RootPackage --> ViewerApp
    RootPackage --> APIEntry
    RenderConfig --> Dockerfile

    %% Click Events
    click EditorApp "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/apps/editor"
    click EditorComponents "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/apps/editor/components"
    click EditorPDF "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/apps/editor/lib/pdf.ts"
    click ViewerApp "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/apps/viewer"
    click ViewerComponents "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/apps/viewer/components"
    click ViewerPDF "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/apps/viewer/lib/pdf.ts"
    click ViewerWorker "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/apps/viewer/lib/search.worker.ts"
    click APIEntry "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/services/api/main.py"
    click Routers "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/routers"
    click Core "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/core"
    click Adapters "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/adapters"
    click SQLite "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/adapters/sqlite"
    click Postgres "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/adapters/pg"
    click SheetsAdapter "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/adapters/sheets"
    click JSONAdapter "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/adapters/json"
    click Models "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/models"
    click Schemas "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/schemas"
    click Settings "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/services/api/settings.py"
    click Dockerfile "https://github.com/aniketsandhanwootz-wq/pdf-markbook/tree/main/services/api/Dockerfile"
    click Requirements "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/services/api/requirements.txt"
    click Migrations "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/infra/sql/001_init.sql"
    click RootPackage "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/package.json"
    click RenderConfig "https://github.com/aniketsandhanwootz-wq/pdf-markbook/blob/main/render.yaml"

    %% Styles
    classDef frontend fill:#d0e7ff,stroke:#0284c7,stroke-width:1px
    classDef api fill:#e0ffe0,stroke:#3cba54,stroke-width:1px
    classDef routers fill:#d4f7d4,stroke:#2d8a2d,stroke-width:1px
    classDef core fill:#fff8b3,stroke:#e0a800,stroke-width:1px
    classDef adapters fill:#ffdd99,stroke:#d67f00,stroke-width:1px
    classDef model fill:#f0f0f0,stroke:#999999,stroke-width:1px
    classDef database fill:#cccccc,stroke:#666666,stroke-width:1px
    classDef external fill:#f3d4ff,stroke:#a64ca6,stroke-width:1px
    classDef infra fill:#ffe8d6,stroke:#d1495b,stroke-width:1px
```
