sandeshchhetri985016/writegy

1. System shape

- The active production architecture is a two-app full stack: a React 18 SPA in frontend/ and a single Spring Boot 3.5 backend in backend/.

- The backend is the central application boundary for business logic, persistence, auth verification, document processing, export, and grammar checking.

- archive/ contains earlier microservice experiments (gateway, user, document, NLP, notification, analytics) but they are historical and not the active runtime path.

2. Frontend subsystem

- The React app is organized by feature: auth, dashboard, editor, settings, and admin.

- frontend/src/lib/api/* wraps backend calls; frontend/src/lib/supabase.js integrates Supabase client-side auth.

- UI state is split across contexts such as AuthContext and EditorContext, with routing protection via ProtectedRoute.

- The editor layer includes rich text, markdown, and canvas editing, plus file upload, grammar suggestion panels, and auto-save behavior.

3. Backend subsystem

- The Spring Boot backend follows a standard layered design: controllers → services → repositories → JPA entities/DTOs.

- Main controllers are AuthController, DocumentController, GrammarController, ExportController, UserController, SettingsController, and AdminController.

- Services encapsulate domain logic such as document management, auth, storage, text extraction, export, and grammar checking.

4. Authentication and security boundary

- Authentication is Supabase-backed on the client, but the backend still enforces access using JWT validation.

- Backend security includes a JWT filter, authentication entry point, CORS config, and rate limiting.

- The common flow is: user signs in with Supabase in the browser, frontend sends the JWT to the backend, and the backend validates it before allowing document or profile operations.

- /auth/sync and /auth/me are the main bridge endpoints for aligning Supabase identity with backend user records.

5. Core data model and persistence

- The persistent domain lives in PostgreSQL via JPA/Hibernate and Flyway migrations.

- Key entities include User, UserProfile, UserPreferences, Document, DocumentVersion, UserEvent, and WritingMetrics.

- The schema history shows document hierarchy and canvas support, indicating the backend stores both classic documents and richer structured content.

- Repositories isolate database access for users, profiles, preferences, and documents.

6. Document lifecycle flow

- Document operations are handled by the backend API: list, create, fetch, update, delete, and hierarchical child-document handling.

- The frontend editor sends document content to the backend, which persists the document metadata/content and version/history data.

- Auto-save happens in the browser, but persistence is centralized in the backend so content survives refreshes and reconnects.

7. File upload and storage flow

- The project uses a hybrid upload pattern: the frontend can extract text from uploaded files first, then send both the file and extracted text to the backend as multipart form data.

- Backend storage is split between database content and object storage.

- StorageService and R2Config indicate an abstraction over external file storage; the README and environment setup point to Supabase Storage as the primary target.

8. Grammar/AI processing

- Grammar checking is exposed by the backend as a dedicated API and consumed by the editor UI for inline suggestions.

- The result is not just a corrected text blob; the UI is designed around suggestions, applying individual fixes, and highlighting affected spans.

- The repo also contains an archived standalone NLP service experiment, showing that AI/grammar processing was explored as a separate service before being folded into the current architecture.

9. Export and document output

- ExportController and ExportService generate downloadable document formats such as PDF, DOCX, and Markdown.

- Export is treated as a backend responsibility because it depends on the persisted document model, formatting rules, and server-side file generation.

10. Operational and deployment boundaries

- The active deployment target is Render for the backend, with Dockerfiles for both frontend and backend.

- docker-compose.yml, render.yaml, Makefile, and the Scripts/ folder support local orchestration, backups, cache clearing, and DB migration workflows.

- backend/src/main/resources/db/migration/ and infra/supabase/migrations/ show two migration tracks: backend-managed schema evolution and Supabase infrastructure setup.

- infra/monitoring/ contains Prometheus/Grafana provisioning, so observability is a first-class operational concern rather than an afterthought.

11. Historical architecture in archive/

- The archived backend experiments reveal a prior microservice decomposition: API gateway, user service, document service, NLP service, notification service, and analytics service.

- These modules are useful for understanding intended bounded contexts, but they are not the current mainline execution path.

- For an architecture diagram, they should be shown separately as legacy/experimental subsystems, not as live dependencies of the current SPA + monolith backend + Supabase stack.