thameem-ali0911/docket

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).