# sandeshchhetri985016/writegy architecture > Architecture diagram of the GitHub repository sandeshchhetri985016/writegy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source. - Interactive diagram: https://gitdiagram.com/sandeshchhetri985016/writegy - Repository: https://github.com/sandeshchhetri985016/writegy ## Overview 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. Main entry points: [`frontend/src/App.jsx`](https://github.com/sandeshchhetri985016/writegy/blob/main/frontend/src/App.jsx) (React SPA), [`backend/src/main/java/com/writegy/WritegyApplication.java`](https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/WritegyApplication.java) (Spring Boot app), [`archive/experiments/backend-services/api-gateway`](https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/api-gateway) (API gateway), [`render.yaml`](https://github.com/sandeshchhetri985016/writegy/blob/main/render.yaml) (Ops tooling) ## Diagram (Mermaid) ```mermaid flowchart TD subgraph group_active["Active system"] end subgraph group_backend["Backend"] node_backend_app["Spring Boot app
monolith backend"] node_backend_security["Security
jwt and rate limit"] node_backend_auth["Auth API
controller/service"] node_backend_documents["Document API
controller/service"] node_backend_grammar["Grammar API
controller/service"] node_backend_export["Export API
controller/service"] node_backend_domain[("Domain model
entities and repos")] node_backend_storage["Storage layer
storage and extraction"] node_backend_db[("PostgreSQL + Flyway
persistent schema")] end subgraph group_frontend["Frontend"] node_frontend_app["React SPA
React 18 client
[App.jsx]"] node_frontend_auth["Auth UI
feature area"] node_frontend_dashboard["Dashboard UI
feature area"] node_frontend_editor["Editor UI
feature area"] node_frontend_settings["Settings UI
feature area"] node_frontend_admin["Admin UI
feature area"] node_frontend_state["Client state
contexts/hooks"] node_frontend_api["API layer
client adapters"] node_frontend_supabase["Supabase client
auth integration
[supabase.js]"] end subgraph group_infra["Infra"] node_ops["Ops tooling
deployment and monitoring
[render.yaml]"] end subgraph group_legacy["Legacy experiments"] node_legacy_gateway["API gateway
legacy service"] node_legacy_user["User service
legacy service"] node_legacy_document["Document service
legacy service"] node_legacy_nlp["NLP service
legacy service"] node_legacy_notification["Notification service
legacy service"] node_legacy_analytics["Analytics service
legacy service"] end node_frontend_app -->|"routes to"| node_frontend_auth node_frontend_app -->|"routes to"| node_frontend_dashboard node_frontend_app -->|"routes to"| node_frontend_editor node_frontend_app -->|"routes to"| node_frontend_settings node_frontend_app -->|"routes to"| node_frontend_admin node_frontend_app -->|"uses"| node_frontend_state node_frontend_app -->|"calls"| node_frontend_api node_frontend_app -->|"auths with"| node_frontend_supabase node_frontend_api -->|"requests"| node_backend_app node_frontend_supabase -->|"bridges via JWT"| node_backend_auth node_backend_app -->|"protected by"| node_backend_security node_backend_app -->|"exposes"| node_backend_auth node_backend_app -->|"exposes"| node_backend_documents node_backend_app -->|"exposes"| node_backend_grammar node_backend_app -->|"exposes"| node_backend_export node_backend_app -->|"persists via"| node_backend_domain node_backend_app -->|"uses"| node_backend_storage node_backend_domain -->|"stored in"| node_backend_db node_backend_storage -->|"tracks metadata in"| node_backend_db node_ops -->|"deploys"| node_backend_app node_ops -->|"builds"| node_frontend_app node_ops -->|"migrates"| node_backend_db node_legacy_gateway -.->|"routes to"| node_legacy_user node_legacy_gateway -.->|"routes to"| node_legacy_document node_legacy_gateway -.->|"routes to"| node_legacy_nlp node_legacy_gateway -.->|"routes to"| node_legacy_notification node_legacy_gateway -.->|"routes to"| node_legacy_analytics node_legacy_user -.->|"shared context"| node_legacy_document node_legacy_document -.->|"paired with"| node_legacy_nlp click node_frontend_app "https://github.com/sandeshchhetri985016/writegy/blob/main/frontend/src/App.jsx" click node_frontend_auth "https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/auth" click node_frontend_dashboard "https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/dashboard" click node_frontend_editor "https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/editor" click node_frontend_settings "https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/settings" click node_frontend_admin "https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/admin" click node_frontend_state "https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/contexts" click node_frontend_api "https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/lib/api" click node_frontend_supabase "https://github.com/sandeshchhetri985016/writegy/blob/main/frontend/src/lib/supabase.js" click node_backend_app "https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/WritegyApplication.java" click node_backend_security "https://github.com/sandeshchhetri985016/writegy/tree/main/backend/src/main/java/com/writegy/security" click node_backend_auth "https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/controller/AuthController.java" click node_backend_documents "https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/controller/DocumentController.java" click node_backend_grammar "https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/controller/GrammarController.java" click node_backend_export "https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/controller/ExportController.java" click node_backend_domain "https://github.com/sandeshchhetri985016/writegy/tree/main/backend/src/main/java/com/writegy/model/entity" click node_backend_storage "https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/service/StorageService.java" click node_backend_db "https://github.com/sandeshchhetri985016/writegy/tree/main/backend/src/main/resources/db/migration" click node_ops "https://github.com/sandeshchhetri985016/writegy/blob/main/render.yaml" click node_legacy_gateway "https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/api-gateway" click node_legacy_user "https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/user-service" click node_legacy_document "https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/document-service" click node_legacy_nlp "https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/nlp-service" click node_legacy_notification "https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/notification-service" click node_legacy_analytics "https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/analytics-service" 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_backend_app,node_backend_security,node_backend_auth,node_backend_documents,node_backend_grammar,node_backend_export,node_backend_domain,node_backend_storage,node_backend_db toneAmber class node_frontend_app,node_frontend_auth,node_frontend_dashboard,node_frontend_editor,node_frontend_settings,node_frontend_admin,node_frontend_state,node_frontend_api,node_frontend_supabase toneMint class node_ops toneRose class node_legacy_gateway,node_legacy_user,node_legacy_document,node_legacy_nlp,node_legacy_notification,node_legacy_analytics toneIndigo ``` ## Components ### Backend Main Spring Boot application boundary for business logic and persistence. - [Spring Boot app](https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/WritegyApplication.java): monolith backend · Main server-side application for auth verification, documents, grammar, export, and settings. · `backend/src/main/java/com/writegy/WritegyApplication.java` - [Security](https://github.com/sandeshchhetri985016/writegy/tree/main/backend/src/main/java/com/writegy/security): jwt and rate limit · JWT filters, auth entry point, CORS, and request throttling. · `backend/src/main/java/com/writegy/security` - [Auth API](https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/controller/AuthController.java): controller/service · Auth bridge endpoints including identity sync and current-user lookup. · `backend/src/main/java/com/writegy/controller/AuthController.java` - [Document API](https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/controller/DocumentController.java): controller/service · Document CRUD, hierarchy, persistence, and versioned content lifecycle. · `backend/src/main/java/com/writegy/controller/DocumentController.java` - [Grammar API](https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/controller/GrammarController.java): controller/service · Grammar checking and suggestion generation for editor assistance. · `backend/src/main/java/com/writegy/controller/GrammarController.java` - [Export API](https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/controller/ExportController.java): controller/service · Server-side generation of PDF, DOCX, and Markdown outputs. · `backend/src/main/java/com/writegy/controller/ExportController.java` - [Domain model](https://github.com/sandeshchhetri985016/writegy/tree/main/backend/src/main/java/com/writegy/model/entity): entities and repos · Users, profiles, preferences, documents, versions, events, and metrics persisted via JPA. · `backend/src/main/java/com/writegy/model/entity` - [Storage layer](https://github.com/sandeshchhetri985016/writegy/blob/main/backend/src/main/java/com/writegy/service/StorageService.java): storage and extraction · Object storage abstraction and text extraction support for uploaded files. · `backend/src/main/java/com/writegy/service/StorageService.java` - [PostgreSQL + Flyway](https://github.com/sandeshchhetri985016/writegy/tree/main/backend/src/main/resources/db/migration): persistent schema · Database schema and migrations for the active backend data model. · `backend/src/main/resources/db/migration` ### Frontend React SPA organized by product features and client-side state. - [React SPA](https://github.com/sandeshchhetri985016/writegy/blob/main/frontend/src/App.jsx): React 18 client · Primary browser application for auth, dashboard, editing, settings, and admin flows. · `frontend/src/App.jsx` - [Auth UI](https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/auth): feature area · Login/register/forgot-password screens and session entry flow. · `frontend/src/features/auth` - [Dashboard UI](https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/dashboard): feature area · Document list, tree view, and recent activity surfaces. · `frontend/src/features/dashboard` - [Editor UI](https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/editor): feature area · Rich text, markdown, canvas editing, uploads, suggestions, and export actions. · `frontend/src/features/editor` - [Settings UI](https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/settings): feature area · Profile, preferences, and subscription screens. · `frontend/src/features/settings` - [Admin UI](https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/features/admin): feature area · Administrative dashboard for privileged user workflows. · `frontend/src/features/admin` - [Client state](https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/contexts): contexts/hooks · Auth and editor context plus auto-save and local storage hooks. · `frontend/src/contexts` - [API layer](https://github.com/sandeshchhetri985016/writegy/tree/main/frontend/src/lib/api): client adapters · Axios-backed API wrappers for auth, documents, export, and grammar calls. · `frontend/src/lib/api` - [Supabase client](https://github.com/sandeshchhetri985016/writegy/blob/main/frontend/src/lib/supabase.js): auth integration · Client-side identity and session management used before backend validation. · `frontend/src/lib/supabase.js` ### Infra Deployment, migrations, monitoring, and local orchestration support. - [Ops tooling](https://github.com/sandeshchhetri985016/writegy/blob/main/render.yaml): deployment and monitoring · Render deployment, Docker, compose, backup/migration scripts, and monitoring config. · `render.yaml` ### Legacy experiments Archived microservice and earlier-service experiments retained for reference. - [API gateway](https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/api-gateway): legacy service · Archived gateway experiment with routing, auth, and rate-limit filters. · `archive/experiments/backend-services/api-gateway` - [User service](https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/user-service): legacy service · Archived auth/profile service experiment backed by Supabase integration. · `archive/experiments/backend-services/user-service` - [Document service](https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/document-service): legacy service · Archived document-processing and storage service experiment. · `archive/experiments/backend-services/document-service` - [NLP service](https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/nlp-service): legacy service · Archived standalone grammar/NLP service experiment. · `archive/experiments/backend-services/nlp-service` - [Notification service](https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/notification-service): legacy service · Archived WebSocket notification service experiment. · `archive/experiments/backend-services/notification-service` - [Analytics service](https://github.com/sandeshchhetri985016/writegy/tree/main/archive/experiments/backend-services/analytics-service): legacy service · Archived event analytics service experiment. · `archive/experiments/backend-services/analytics-service` ## Connections - React SPA → Auth UI: routes to · Auth screens are part of the SPA route tree. - React SPA → Dashboard UI: routes to · Dashboard is the main post-login surface. - React SPA → Editor UI: routes to · Editor hosts document creation and editing workflows. - React SPA → Settings UI: routes to · Settings screens manage profile and preferences. - React SPA → Admin UI: routes to · Admin surface is exposed within the SPA. - React SPA → Client state: uses · Shared contexts and hooks manage session and editor state. - React SPA → API layer: calls · UI actions are translated into backend API requests. - React SPA → Supabase client: auths with · Client-side sign-in uses Supabase before backend verification. - API layer → Spring Boot app: requests · Frontend API wrappers send document, export, grammar, and auth traffic to the backend. - Supabase client → Auth API: bridges via JWT · Supabase identity is synchronized and validated through backend auth endpoints. - Spring Boot app → Security: protected by · Requests are filtered through JWT, CORS, and rate limiting. - Spring Boot app → Auth API: exposes · Auth endpoints align external identity with backend user records. - Spring Boot app → Document API: exposes · Document lifecycle endpoints manage content and hierarchy. - Spring Boot app → Grammar API: exposes · Grammar checking is served from the backend. - Spring Boot app → Export API: exposes · Export endpoints generate downloadable artifacts. - Spring Boot app → Domain model: persists via · Services operate over JPA entities and repositories. - Spring Boot app → Storage layer: uses · Uploads and extraction flow through object storage and parsing services. - Domain model → PostgreSQL + Flyway: stored in · Entities are mapped to the PostgreSQL schema managed by Flyway. - Storage layer → PostgreSQL + Flyway: tracks metadata in · Stored files are associated with persisted document records. - Ops tooling → Spring Boot app: deploys · Render and Docker-based operations target the backend service. - Ops tooling → React SPA: builds · Frontend has its own Dockerized build and local runtime support. - Ops tooling → PostgreSQL + Flyway: migrates · Database migrations and scripts manage schema evolution. - API gateway → User service: routes to · Gateway experiment forwarded auth and profile traffic. - API gateway → Document service: routes to · Gateway experiment forwarded document traffic. - API gateway → NLP service: routes to · Gateway experiment forwarded NLP traffic. - API gateway → Notification service: routes to · Gateway experiment forwarded notifications. - API gateway → Analytics service: routes to · Gateway experiment forwarded analytics traffic. - User service → Document service: shared context · Historical services reflect earlier bounded-context splitting. - Document service → NLP service: paired with · Document and NLP were separate experiments before consolidation.