# farhansytech/ns-reqford-reactjs-springboot-mssql architecture

> Architecture diagram of the GitHub repository farhansytech/ns-reqford-reactjs-springboot-mssql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/farhansytech/ns-reqford-reactjs-springboot-mssql
- Repository: https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql

## Overview

1. **Overall shape**
   - This repository is a full-stack monorepo with a **Spring Boot backend** and a **React frontend**.
   - The deployed backend also serves a compiled frontend from `src/main/resources/static`, so the application can run as a single server process with browser clients on top.

2. **Primary runtime boundary**
   - The backend is the system of record and exposes REST APIs plus WebSocket messaging.
   - The frontend is a thin client that handles screens, dialogs, and workflow state, and talks to backend endpoints through `frontend/src/api.js`.

3. **Frontend application structure**
   - React is organized by concern: `pages` for route-level screens, `components` for document/chat modals and editors, `dashboards` for role-specific views, `guards` for auth/admin protection, and `hooks` for document locking.
   - The UI is heavily workflow-driven: login/register, role dashboards, chat, document search/editing, admin management, and audit views.

4. **Backend layering**
   - The backend follows a standard controller/service/repository split.
   - `controller` classes expose HTTP endpoints, `service` classes contain business rules, `repository` interfaces access MSSQL via JPA/Hibernate, and `model` classes map to persisted entities.
   - `dto` objects are used for request/response boundaries so the API does not directly expose entity objects.

5. **Core domain subsystems**
   - **Authentication and identity**: JWT-based security, user details service, auth controller, role management, and admin role policies.
   - **Chat and messaging**: chat threads, messages, visibility/permissions, and role-based dashboard switching.
   - **Document management**: upload, edit, merge, lock, search, stamp, audit, and type-specific handling.
   - **Email/Gmail integration**: inbox/outbox, token handling, email sync, and import/send flows.
   - **Audit and compliance**: audit logs are recorded for key user actions and document changes.

6. **Document workflow architecture**
   - Documents appear to be a major business object with multiple specialized types: upload records, Type Two documents/comments, and document lineage/history.
   - Editing and merge operations are isolated in services such as `DocumentEditorService`, `DocumentMergeController`, `DocumentConversionService`, `TypeTwoPdfService`, and `WatermarkService`.
   - The system preserves historical versions using filesystem backups under `uploads/documents/backup`, while active files live under `uploads/documents/active`.

7. **File and PDF processing pipeline**
   - Uploaded documents are stored on disk rather than only in the database.
   - Services like `FileService`, `PdfMetadataExtractorService`, `PdfStampService`, `ScannedStampExtractorService`, and `StampService` handle PDF metadata, annotations, stamp placement, and visual approval marks.
   - This creates a clear split between database metadata and filesystem binary assets.

8. **OCR and document intelligence**
   - OCR is a separate capability powered by Tesseract, configured through `application.properties`.
   - OCR output is used to extract metadata such as file numbers from scanned PDFs, which then feeds document search, classification, and stamp/route logic.
   - Supporting services include `OcrService` and `FileNumberDetectionService`.

9. **Locking and concurrency control**
   - Document editing is protected by lock/session logic with `DocumentLockService`, `EditorSession`, and a `useDocumentLock` frontend hook.
   - This indicates collaborative or multi-user edit safety is an explicit subsystem, not just a UI concern.
   - Locks likely coordinate with backend state to prevent conflicting edits and to warn users via lock-warning modals.

10. **Role-based workflow and permissions**
   - The application has distinct operational roles such as Secretary, President, Managers, Staff, and Admin.
   - Permission logic is centralized in services like `DashboardPermissionService`, `MessagePermissionService`, `RoleHierarchyService`, and `SpecialForwardPermissionService`.
   - The frontend mirrors this with role dashboards, guarded routes, and role-aware views.

11. **External integrations**
   - **MSSQL** is the relational database and persistent source for users, messages, documents, audit logs, and email tokens.
   - **WebSockets with STOMP/SockJS** provide real-time chat and workflow updates.
   - **Gmail/Google APIs** support email bridging and inbox synchronization.
   - The README also indicates SSL/HTTPS readiness for secure deployment.

12. **Configuration and platform concerns**
   - Backend cross-cutting configuration is split into security, CORS, MVC, async execution, WebSocket auth, and Gmail/OCR setup.
   - `DatabaseSeeder` and `DatabaseMigrationService` suggest startup-time data or schema management support.
   - The presence of packaged frontend assets and file-system logs/backups indicates an on-premise deployment model with local operational state.

13. **Operational data stores**
   - Database tables hold structured records: users, roles, chats/messages, documents, document sequences/file numbers, audit logs, inbox/outbox entries, Gmail tokens, and editor sessions.
   - The filesystem holds mutable binary assets and historical backups under `uploads/`.
   - Application logs are persisted separately under `logs/`, which matters for observability and troubleshooting.

14. **Testing and quality boundaries**
   - Backend tests exist under `src/test/java`, including PDF-related coverage.
   - Frontend end-to-end tests are organized in `frontend/tests`, with page objects and scenario specs for login, dashboard navigation, messaging, admin functions, document management, and audit logs.
   - This suggests the project validates full workflow paths across both UI and backend boundaries.

Main entry points: [`secretary-chat/src/main/java/com/example/secretarychat/service`](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service) (Services), [`secretary-chat/frontend/src/App.js`](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/frontend/src/App.js) (React app), [`secretary-chat/src/main/java/com/example/secretarychat/controller`](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/controller) (Controllers), [`secretary-chat/src/main/java/com/example/secretarychat/repository`](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/repository) (Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_webapp["React app<br/>spa client<br/>[App.js]"]
  node_api_client["API client<br/>frontend api<br/>[api.js]"]
  node_ui_pages["Screens<br/>route views"]
  node_ui_components["Workflows<br/>ui modules"]
  node_ui_dashboards["Role views<br/>role ui"]
  node_ui_guards["Route guards<br/>auth guard"]
  node_ui_locks["Lock hooks<br/>client lock"]
end

subgraph group_backend["Backend"]
  node_server_app["Spring app<br/>boot server"]
  node_web_config["Platform config<br/>spring config"]
  node_security["Security<br/>jwt auth"]
  node_controllers["Controllers<br/>rest api"]
  node_services["Services<br/>business logic"]
  node_admin_services["Admin core<br/>admin services"]
  node_domain_models[("Domain models<br/>jpa entities")]
  node_repositories["Repositories<br/>jpa repos"]
  node_dtos["DTOs<br/>api boundary"]
  node_authz_rules["Permission rules<br/>policy layer"]
  node_document_pipeline["Doc pipeline<br/>file/pdf flow"]
  node_email_bridge["Email bridge<br/>gmail sync"]
end

subgraph group_storage["Storage"]
  node_data_store[("Data store<br/>mssql + files")]
end

subgraph group_integrations["Integrations"]
  node_realtime["Realtime<br/>websocket stomp"]
  node_gmail_api["Google APIs<br/>gmail integration<br/>[GmailConfig.java]"]
end

node_webapp -->|"calls"| node_api_client
node_webapp -->|"renders"| node_ui_pages
node_webapp -->|"composes"| node_ui_components
node_webapp -->|"switches"| node_ui_dashboards
node_webapp -->|"protects"| node_ui_guards
node_webapp -->|"uses"| node_ui_locks
node_api_client -->|"invokes"| node_controllers
node_server_app -->|"boots"| node_web_config
node_server_app -->|"secures"| node_security
node_controllers -->|"delegates"| node_services
node_services -->|"reads/writes"| node_repositories
node_repositories -->|"maps"| node_domain_models
node_controllers -->|"binds"| node_dtos
node_services -->|"enforces"| node_authz_rules
node_services -->|"processes"| node_document_pipeline
node_services -->|"syncs"| node_email_bridge
node_services -->|"publishes"| node_realtime
node_services -->|"persists files"| node_data_store
node_repositories -->|"persists records"| node_data_store
node_email_bridge -->|"connects"| node_gmail_api
node_ui_components -->|"subscribes"| node_realtime
node_ui_locks -->|"checks lock"| node_controllers
node_admin_services -->|"powers"| node_controllers
node_security -->|"applies"| node_authz_rules
node_controllers -->|"serves assets"| node_data_store

click node_webapp "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/frontend/src/App.js"
click node_api_client "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/frontend/src/api.js"
click node_ui_pages "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/pages"
click node_ui_components "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/components"
click node_ui_dashboards "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/dashboards"
click node_ui_guards "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/guards"
click node_ui_locks "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/hooks"
click node_server_app "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/src/main/java/com/example/secretarychat/SecretaryChatApplication.java"
click node_web_config "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/config"
click node_security "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/security"
click node_controllers "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/controller"
click node_services "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service"
click node_admin_services "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service/admin"
click node_domain_models "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/model"
click node_repositories "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/repository"
click node_dtos "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/dto"
click node_authz_rules "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service"
click node_document_pipeline "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service"
click node_email_bridge "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service"
click node_data_store "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/uploads"
click node_realtime "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/src/main/java/com/example/secretarychat/config/WebSocketConfig.java"
click node_gmail_api "https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/src/main/java/com/example/secretarychat/config/GmailConfig.java"

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_webapp,node_api_client,node_ui_pages,node_ui_components,node_ui_dashboards,node_ui_guards,node_ui_locks toneBlue
class node_server_app,node_web_config,node_security,node_controllers,node_services,node_admin_services,node_domain_models,node_repositories,node_dtos,node_authz_rules,node_document_pipeline,node_email_bridge toneAmber
class node_data_store toneMint
class node_realtime,node_gmail_api toneRose
```

## Components

### Frontend

React UI and client-side workflow logic

- [React app](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/frontend/src/App.js): spa client · Browser UI for login, dashboards, chat, and document workflows · `secretary-chat/frontend/src/App.js`
- [API client](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/frontend/src/api.js): frontend api · HTTP bridge used by the UI to call backend endpoints · `secretary-chat/frontend/src/api.js`
- [Screens](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/pages): route views · Route-level pages for auth, dashboards, search, admin, and audit · `secretary-chat/frontend/src/pages`
- [Workflows](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/components): ui modules · Chat, document editor, mail, merge, preview, and modal workflows · `secretary-chat/frontend/src/components`
- [Role views](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/dashboards): role ui · Role-specific dashboards and dashboard switching · `secretary-chat/frontend/src/dashboards`
- [Route guards](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/guards): auth guard · Protected route wrappers for authenticated and admin-only access · `secretary-chat/frontend/src/guards`
- [Lock hooks](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/frontend/src/hooks): client lock · Hooks that coordinate document lock state in the UI · `secretary-chat/frontend/src/hooks`

### Backend

Spring Boot API, security, and business services

- [Spring app](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/src/main/java/com/example/secretarychat/SecretaryChatApplication.java): boot server · Backend entrypoint and packaged server that also serves static frontend assets · `secretary-chat/src/main/java/com/example/secretarychat/SecretaryChatApplication.java`
- [Platform config](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/config): spring config · Cross-cutting backend configuration for MVC, CORS, async, WebSocket, and Gmail · `secretary-chat/src/main/java/com/example/secretarychat/config`
- [Security](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/security): jwt auth · JWT filter, user details service, and Spring Security configuration · `secretary-chat/src/main/java/com/example/secretarychat/security`
- [Controllers](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/controller): rest api · HTTP endpoints for auth, chat, documents, inbox, admin, and audit · `secretary-chat/src/main/java/com/example/secretarychat/controller`
- [Services](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service): business logic · Core business rules for chat, documents, email, locking, OCR, and permissions · `secretary-chat/src/main/java/com/example/secretarychat/service`
- [Admin core](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service/admin): admin services · Admin-specific user, role, department, and dashboard management · `secretary-chat/src/main/java/com/example/secretarychat/service/admin`
- [Domain models](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/model): jpa entities · Persistent entities for users, roles, chats, messages, documents, email, and audit · `secretary-chat/src/main/java/com/example/secretarychat/model`
- [Repositories](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/repository): jpa repos · Database access layer for persisted domain records · `secretary-chat/src/main/java/com/example/secretarychat/repository`
- [DTOs](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/dto): api boundary · Request and response objects used to isolate the API from entities · `secretary-chat/src/main/java/com/example/secretarychat/dto`
- [Permission rules](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service): policy layer · Role hierarchy and dashboard/message/forward permission policies · `secretary-chat/src/main/java/com/example/secretarychat/service`
- [Doc pipeline](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service): file/pdf flow · Document conversion, editing, locking, stamping, OCR, metadata extraction, and file-number detection · `secretary-chat/src/main/java/com/example/secretarychat/service`
- [Email bridge](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/src/main/java/com/example/secretarychat/service): gmail sync · Gmail tokens, inbox/outbox sync, and email import/send flows · `secretary-chat/src/main/java/com/example/secretarychat/service`

### Storage

Database, uploaded files, logs, and runtime artifacts

- [Data store](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/tree/master/secretary-chat/uploads): mssql + files · MSSQL data plus uploads, backups, logs, and other runtime files · `secretary-chat/uploads`

### Integrations

External services and realtime transport

- [Realtime](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/src/main/java/com/example/secretarychat/config/WebSocketConfig.java): websocket stomp · STOMP/SockJS messaging for chat and live workflow updates · `secretary-chat/src/main/java/com/example/secretarychat/config/WebSocketConfig.java`
- [Google APIs](https://github.com/farhansytech/ns-reqford-reactjs-springboot-mssql/blob/master/secretary-chat/src/main/java/com/example/secretarychat/config/GmailConfig.java): gmail integration · External Gmail connectivity used for inbox and message bridging · `secretary-chat/src/main/java/com/example/secretarychat/config/GmailConfig.java`

## Connections

- React app → API client: calls · UI uses a dedicated client module for backend requests
- React app → Screens: renders · App routes to page-level screens
- React app → Workflows: composes · Screens are built from workflow components and modals
- React app → Role views: switches · Role-aware dashboards drive the main user experience
- React app → Route guards: protects · Authenticated and admin routes are guarded on the client
- React app → Lock hooks: uses · Frontend lock hooks coordinate editor safety
- API client → Controllers: invokes · HTTP client targets REST controllers
- Spring app → Platform config: boots · Application starts with platform and integration config
- Spring app → Security: secures · Server enforces JWT-based authentication and authorization
- Controllers → Services: delegates · Controllers pass business work to services
- Services → Repositories: reads/writes · Services persist and query domain state through repositories
- Repositories → Domain models: maps · Repositories persist JPA entities
- Controllers → DTOs: binds · API endpoints exchange DTOs rather than entities
- Services → Permission rules: enforces · Permission services and role hierarchy govern workflows
- Services → Doc pipeline: processes · Document-related services handle editing, conversion, stamping, OCR, and locks
- Services → Email bridge: syncs · Email services handle Gmail and inbox/outbox flows
- Services → Realtime: publishes · Chat and workflow events are pushed over WebSockets
- Services → Data store: persists files · Document binaries, backups, logs, and runtime artifacts live on disk
- Repositories → Data store: persists records · Structured application data is stored in MSSQL
- Email bridge → Google APIs: connects · Backend Gmail integration depends on external Google services
- Workflows → Realtime: subscribes · Chat UI listens to live updates through the realtime layer
- Lock hooks → Controllers: checks lock · Document locking coordinates with backend lock endpoints
- Admin core → Controllers: powers · Admin controllers are backed by admin-specific services
- Security → Permission rules: applies · Security layer uses role and policy rules
- Controllers → Data store: serves assets · Backend serves packaged frontend assets and static files
