# thameem-ali0911/docket architecture

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

- Interactive diagram: https://gitdiagram.com/thameem-ali0911/docket
- Repository: https://github.com/thameem-ali0911/docket

## Overview

#### 1. Purpose and Top-Level Shape
Docket is a B2B document-intelligence MVP: authenticated users upload invoices, contracts, or resumes; the backend stores and processes them for extracted text and later AI-derived outputs. The implemented repository is a React SPA plus Spring Boot REST API, PostgreSQL schema migrations, local file uploads, and Docker Compose orchestration.

Entry points: `frontend/src/main.jsx`, `frontend/src/App.jsx`, and `backend/src/main/java/com/docket/DocketApplication.java`. Full-stack startup is defined by `docker-compose.yml`.

#### 2. Frontend Application and API Boundary
The browser client presents login/signup, dashboard, and upload flows. Route protection is client-side; API interaction is centralized rather than embedded in pages.

Key paths:
- `frontend/src/App.jsx`
- `frontend/src/components/ProtectedRoute.jsx`
- `frontend/src/lib/api.js`
- `frontend/src/pages/Dashboard.jsx`
- `frontend/src/pages/UploadDocument.jsx`

Control flow is: user authenticates, client retains session/token state, protected views call the backend API, and upload/dashboard views render document records. The frontend is built by Vite and served through nginx in its container (`frontend/Dockerfile`, `frontend/nginx.conf`).

#### 3. API, Authentication, and Security
Spring MVC controllers expose the principal REST boundary: auth, documents, and health. Auth registration/login creates a workspace/user context and returns JWT-based credentials. Subsequent requests are authenticated by a JWT filter; Spring Security controls endpoint access and CORS/web behavior.

Key paths:
- `backend/src/main/java/com/docket/controller/AuthController.java`
- `backend/src/main/java/com/docket/controller/DocumentController.java`
- `backend/src/main/java/com/docket/service/AuthService.java`
- `backend/src/main/java/com/docket/security/JwtAuthFilter.java`
- `backend/src/main/java/com/docket/config/SecurityConfig.java`

Exceptions are normalized at the API boundary through `backend/src/main/java/com/docket/exception/GlobalExceptionHandler.java`.

#### 4. Document Lifecycle and Processing Pipeline
Document upload is the central vertical flow. `DocumentController` delegates lifecycle and persistence work to `DocumentService`; a document record tracks type and processing status. Processing separates file/text handling from the document-facing service layer.

Key paths:
- `backend/src/main/java/com/docket/service/DocumentService.java`
- `backend/src/main/java/com/docket/service/DocumentProcessingService.java`
- `backend/src/main/java/com/docket/entity/Document.java`
- `backend/src/main/java/com/docket/entity/DocumentStatus.java`
- `backend/src/main/java/com/docket/entity/DocumentType.java`

The intended pipeline is upload → durable file storage and document metadata → PDF text extraction or OCR fallback → persisted raw text → later structured extraction, summary, and anomaly results. Processing is synchronous; no queue or worker runtime is present.

#### 5. OCR and File Storage Boundary
OCR/PDF extraction and filesystem persistence are explicit service boundaries, allowing higher-level document workflows to avoid direct dependence on Tesseract or file paths.

Key paths:
- `backend/src/main/java/com/docket/service/OcrService.java`
- `backend/src/main/java/com/docket/service/OcrResult.java`
- `backend/src/main/java/com/docket/service/StorageService.java`
- `backend/uploads`

Material runtime dependencies are Tess4J/Tesseract and Apache PDFBox (per project stack), with Tesseract language data configured externally. Uploads are currently local filesystem artifacts, not object storage.

#### 6. Persistence Model and Database Evolution
JPA entities represent workspace tenancy, users, and documents; Spring Data repositories isolate database access. PostgreSQL is the system of record. Flyway migrations define the schema and evolution, including raw OCR/extracted text.

Key paths:
- `backend/src/main/java/com/docket/entity/Workspace.java`
- `backend/src/main/java/com/docket/entity/User.java`
- `backend/src/main/java/com/docket/repository/DocumentRepository.java`
- `backend/src/main/resources/db/migration/V1__init_schema.sql`
- `backend/src/main/resources/db/migration/V3__add_raw_text_to_documents.sql`

Ownership/workspace association is the key data-isolation boundary for document access.

#### 7. Deployment and External Services
`docker-compose.yml` runs PostgreSQL, backend, and frontend together. Backend packaging is defined in `backend/Dockerfile`; frontend is compiled then served statically. Spring configuration lives in `backend/src/main/resources/application.yml`.

The planned AI boundary is Google Gemini, configured through `GEMINI_API_KEY`; no Gemini client/prompt package appears in the current tree. JWT secrets, database credentials, API base URL, and Tesseract data paths are environment-configured (`.env.example`, `frontend/.env.example`).

Main entry points: [`backend/src/main/java/com/docket/controller/DocumentController.java`](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/controller/DocumentController.java) (REST controllers), [`backend/src/main/java/com/docket/service/DocumentProcessingService.java`](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/DocumentProcessingService.java) (Document processing), [`frontend/src/App.jsx`](https://github.com/thameem-ali0911/docket/blob/main/frontend/src/App.jsx) (React SPA), [`backend/src/main/java/com/docket/repository/DocumentRepository.java`](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/repository/DocumentRepository.java) (JPA repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser client"]
  node_browser(("User browser"))
  node_spa["React SPA<br/>Vite React<br/>[App.jsx]"]
  node_protected_route["Route protection<br/>React guard<br/>[ProtectedRoute.jsx]"]
  node_api_client["API client<br/>frontend API layer<br/>[api.js]"]
end

subgraph group_backend["Spring Boot API"]
  node_api_controllers["REST controllers<br/>Spring MVC"]
  node_security["JWT security<br/>Spring Security<br/>[JwtAuthFilter.java]"]
  node_auth_service["Authentication service<br/>[AuthService.java]"]
  node_document_service["Document lifecycle"]
  node_processing["Document processing<br/>synchronous pipeline"]
  node_ocr["PDF/OCR extraction<br/>PDFBox + Tess4J<br/>[OcrService.java]"]
  node_exception_handler["API error handler<br/>exception boundary"]
end

subgraph group_data["Persistence &amp; storage"]
  node_repositories["JPA repositories<br/>Spring Data"]
  node_domain_model["Workspace, user &amp; document<br/>JPA entities<br/>[Document.java]"]
  node_postgres[("PostgreSQL<br/>system of record")]
  node_flyway["Flyway migrations<br/>schema evolution"]
  node_storage["Local upload storage<br/>filesystem"]
end

subgraph group_runtime["Deployment"]
  node_compose["Docker Compose<br/>orchestration<br/>[docker-compose.yml]"]
  node_backend_app["Backend application<br/>Spring Boot entry point"]
  node_frontend_container["Frontend container<br/>Vite build + nginx"]
end

node_gemini{{"Google Gemini<br/>planned AI provider"}}

node_browser -->|"uses"| node_spa
node_spa -->|"guards views"| node_protected_route
node_spa -->|"calls through"| node_api_client
node_api_client -->|"REST requests"| node_api_controllers
node_api_controllers -->|"secured by"| node_security
node_api_controllers -->|"login / signup"| node_auth_service
node_api_controllers -->|"document operations"| node_document_service
node_api_controllers -->|"normalized errors"| node_exception_handler
node_document_service -->|"processes upload"| node_processing
node_document_service -->|"persists metadata"| node_repositories
node_processing -->|"extracts text"| node_ocr
node_processing -->|"stores source file"| node_storage
node_processing -->|"persists raw text/status"| node_repositories
node_repositories -->|"maps"| node_domain_model
node_repositories -->|"reads / writes"| node_postgres
node_flyway -->|"migrates"| node_postgres
node_compose -->|"runs"| node_frontend_container
node_compose -->|"runs"| node_backend_app
node_compose -->|"runs"| node_postgres
node_frontend_container -->|"serves"| node_spa
node_backend_app -->|"hosts"| node_api_controllers
node_processing -.->|"future structured AI outputs"| node_gemini

click node_spa "https://github.com/thameem-ali0911/docket/blob/main/frontend/src/App.jsx"
click node_protected_route "https://github.com/thameem-ali0911/docket/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_api_client "https://github.com/thameem-ali0911/docket/blob/main/frontend/src/lib/api.js"
click node_api_controllers "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/controller/DocumentController.java"
click node_security "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/security/JwtAuthFilter.java"
click node_auth_service "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/AuthService.java"
click node_document_service "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/DocumentService.java"
click node_processing "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/DocumentProcessingService.java"
click node_ocr "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/OcrService.java"
click node_exception_handler "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/exception/GlobalExceptionHandler.java"
click node_repositories "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/repository/DocumentRepository.java"
click node_domain_model "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/entity/Document.java"
click node_flyway "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/resources/db/migration/V1__init_schema.sql"
click node_storage "https://github.com/thameem-ali0911/docket/tree/main/backend/uploads"
click node_compose "https://github.com/thameem-ali0911/docket/blob/main/docker-compose.yml"
click node_backend_app "https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/DocketApplication.java"
click node_frontend_container "https://github.com/thameem-ali0911/docket/blob/main/frontend/Dockerfile"

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_browser,node_spa,node_protected_route,node_api_client toneBlue
class node_api_controllers,node_security,node_auth_service,node_document_service,node_processing,node_ocr,node_exception_handler toneAmber
class node_repositories,node_domain_model,node_postgres,node_flyway,node_storage toneMint
class node_compose,node_backend_app,node_frontend_container toneRose
class node_gemini toneNeutral
```

## Components

### Browser client

- **User browser**: browser
- [React SPA](https://github.com/thameem-ali0911/docket/blob/main/frontend/src/App.jsx): Vite React · Login, dashboard, and document upload views. · `frontend/src/App.jsx`
- [Route protection](https://github.com/thameem-ali0911/docket/blob/main/frontend/src/components/ProtectedRoute.jsx): React guard · `frontend/src/components/ProtectedRoute.jsx`
- [API client](https://github.com/thameem-ali0911/docket/blob/main/frontend/src/lib/api.js): frontend API layer · `frontend/src/lib/api.js`

### Spring Boot API

- [REST controllers](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/controller/DocumentController.java): Spring MVC · Auth, document, and health endpoints. · `backend/src/main/java/com/docket/controller/DocumentController.java`
- [JWT security](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/security/JwtAuthFilter.java): Spring Security · JWT filter authenticates requests and controls access. · `backend/src/main/java/com/docket/security/JwtAuthFilter.java`
- [Authentication service](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/AuthService.java): service · Creates workspace/user context and JWT credentials. · `backend/src/main/java/com/docket/service/AuthService.java`
- [Document lifecycle](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/DocumentService.java): service · Applies document ownership, status, and persistence workflows. · `backend/src/main/java/com/docket/service/DocumentService.java`
- [Document processing](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/DocumentProcessingService.java): synchronous pipeline · Extracts text during the upload lifecycle. · `backend/src/main/java/com/docket/service/DocumentProcessingService.java`
- [PDF/OCR extraction](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/service/OcrService.java): PDFBox + Tess4J · Uses PDF text extraction with OCR fallback. · `backend/src/main/java/com/docket/service/OcrService.java`
- [API error handler](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/exception/GlobalExceptionHandler.java): exception boundary · `backend/src/main/java/com/docket/exception/GlobalExceptionHandler.java`

### Persistence & storage

- [JPA repositories](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/repository/DocumentRepository.java): Spring Data · Isolates database access for tenancy and documents. · `backend/src/main/java/com/docket/repository/DocumentRepository.java`
- [Workspace, user & document](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/entity/Document.java): JPA entities · Workspace ownership isolates document access; documents retain type, status, and raw text. · `backend/src/main/java/com/docket/entity/Document.java`
- **PostgreSQL**: system of record
- [Flyway migrations](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/resources/db/migration/V1__init_schema.sql): schema evolution · Defines initial schema and raw-text storage. · `backend/src/main/resources/db/migration/V1__init_schema.sql`
- [Local upload storage](https://github.com/thameem-ali0911/docket/tree/main/backend/uploads): filesystem · Durable uploaded-file artifacts. · `backend/uploads`

### Deployment

- [Docker Compose](https://github.com/thameem-ali0911/docket/blob/main/docker-compose.yml): orchestration · Runs frontend, backend, and PostgreSQL together. · `docker-compose.yml`
- [Backend application](https://github.com/thameem-ali0911/docket/blob/main/backend/src/main/java/com/docket/DocketApplication.java): Spring Boot entry point · `backend/src/main/java/com/docket/DocketApplication.java`
- [Frontend container](https://github.com/thameem-ali0911/docket/blob/main/frontend/Dockerfile): Vite build + nginx · `frontend/Dockerfile`

### Other components

- **Google Gemini**: planned AI provider · Configured by environment but not implemented in the current tree.

## Connections

- User browser → React SPA: uses
- React SPA → Route protection: guards views
- React SPA → API client: calls through
- API client → REST controllers: REST requests
- REST controllers → JWT security: secured by
- REST controllers → Authentication service: login / signup
- REST controllers → Document lifecycle: document operations
- REST controllers → API error handler: normalized errors
- Document lifecycle → Document processing: processes upload
- Document lifecycle → JPA repositories: persists metadata
- Document processing → PDF/OCR extraction: extracts text
- Document processing → Local upload storage: stores source file
- Document processing → JPA repositories: persists raw text/status
- JPA repositories → Workspace, user & document: maps
- JPA repositories → PostgreSQL: reads / writes
- Flyway migrations → PostgreSQL: migrates
- Docker Compose → Frontend container: runs
- Docker Compose → Backend application: runs
- Docker Compose → PostgreSQL: runs
- Frontend container → React SPA: serves
- Backend application → REST controllers: hosts
- Document processing → Google Gemini: future structured AI outputs