How farhansytech/ns-reqford-reactjs-springboot-mssql works
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: service Services · App.js React app · controller Controllers · repository Repositories
Components 22
Frontend
React UI and client-side workflow logic
- React app · Browser UI for login, dashboards, chat, and document workflows
secretary-chat/frontend/src/App.js - API client · HTTP bridge used by the UI to call backend endpoints
secretary-chat/frontend/src/api.js - Screens · Route-level pages for auth, dashboards, search, admin, and audit
secretary-chat/frontend/src/pages - Workflows · Chat, document editor, mail, merge, preview, and modal workflows
secretary-chat/frontend/src/components - Role views · Role-specific dashboards and dashboard switching
secretary-chat/frontend/src/dashboards - Route guards · Protected route wrappers for authenticated and admin-only access
secretary-chat/frontend/src/guards - Lock hooks · Hooks that coordinate document lock state in the UI
secretary-chat/frontend/src/hooks
Backend
Spring Boot API, security, and business services
- Spring app · Backend entrypoint and packaged server that also serves static frontend assets
secretary-chat/src/main/java/com/example/secretarychat/SecretaryChatApplication.java - Platform config · Cross-cutting backend configuration for MVC, CORS, async, WebSocket, and Gmail
secretary-chat/src/main/java/com/example/secretarychat/config - Security · JWT filter, user details service, and Spring Security configuration
secretary-chat/src/main/java/com/example/secretarychat/security - Controllers · HTTP endpoints for auth, chat, documents, inbox, admin, and audit
secretary-chat/src/main/java/com/example/secretarychat/controller - Services · Core business rules for chat, documents, email, locking, OCR, and permissions
secretary-chat/src/main/java/com/example/secretarychat/service - Admin core · Admin-specific user, role, department, and dashboard management
secretary-chat/src/main/java/com/example/secretarychat/service/admin - Domain models · Persistent entities for users, roles, chats, messages, documents, email, and audit
secretary-chat/src/main/java/com/example/secretarychat/model - Repositories · Database access layer for persisted domain records
secretary-chat/src/main/java/com/example/secretarychat/repository - DTOs · Request and response objects used to isolate the API from entities
secretary-chat/src/main/java/com/example/secretarychat/dto - Permission rules · Role hierarchy and dashboard/message/forward permission policies
secretary-chat/src/main/java/com/example/secretarychat/service - Doc pipeline · Document conversion, editing, locking, stamping, OCR, metadata extraction, and file-number detection
secretary-chat/src/main/java/com/example/secretarychat/service - Email bridge · 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 · MSSQL data plus uploads, backups, logs, and other runtime files
secretary-chat/uploads
Integrations
External services and realtime transport
- Realtime · STOMP/SockJS messaging for chat and live workflow updates
secretary-chat/src/main/java/com/example/secretarychat/config/WebSocketConfig.java - Google APIs · External Gmail connectivity used for inbox and message bridging
secretary-chat/src/main/java/com/example/secretarychat/config/GmailConfig.java
Connections 25
- 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