How aniketsandhanwootz-wq/pdf-markbook works
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.