# chandru2002-2/corex-project architecture

> Architecture diagram of the GitHub repository chandru2002-2/corex-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chandru2002-2/corex-project
- Repository: https://github.com/chandru2002-2/corex-project

## Overview

1. **Repository shape**
   - This is a full-stack repo with a **Spring Boot backend** under `backend/` and a **React frontend** at the repo root (`src/`, `public/`, `index.html`).
   - The system is centered on a **secure API platform** rather than a generic CRUD app: authentication, authorization, audit logging, and request metrics are core concerns.

2. **Backend entrypoint and runtime**
   - `CorexApplication.java` is the Spring Boot bootstrap class.
   - The backend runs as a standalone Java service on **localhost:8080** and exposes REST endpoints consumed by the UI.

3. **Layered backend architecture**
   - The backend follows a clean layered structure:
     - `controller` for HTTP endpoints
     - `service` for business logic
     - `repository` for persistence
     - `entity` for JPA models
     - `dto` for request/response payloads
     - `security` for filters and token handling
     - `config` for security and CORS setup
   - This separation is important for the diagram: controllers do not appear to own state directly; they delegate to services and repositories.

4. **Authentication subsystem**
   - `AuthController` and `AuthService` handle registration, login, admin creation, token refresh, and logout.
   - JWT handling is centralized in `JwtUtil`, with token validation and security-context population happening in `JwtFilter`.
   - The system is designed to be **stateless**: no server session is used for authentication, and Spring Security is configured accordingly.

5. **Authorization and access control**
   - Access is role-based, with **ADMIN** and **USER** roles represented in the model layer (`Role` entity).
   - `SecurityConfig` enforces endpoint boundaries such as public auth routes and protected admin/user routes.
   - `RoleTestController` appears to exist as a role-protected test endpoint for validating access control behavior.

6. **Security filter chain**
   - The backend uses custom servlet filters to augment the request pipeline:
     - `JwtFilter` authenticates incoming requests
     - `MetricsFilter` records API usage/performance
     - `AuditFilter` captures request audit data
   - The README indicates this custom chain is ordered as `JwtFilter → MetricsFilter → AuditFilter`, which is a key architectural boundary: security and observability happen before controller execution.

7. **Observability and auditing**
   - `AuditController` and `MetricsController` expose admin-facing views of the collected telemetry.
   - `AuditLog` and `Metrics` entities, plus their repositories, persist request history and usage stats.
   - This means every API call is not just handled functionally; it also feeds an internal monitoring/audit pipeline used by administrators.

8. **Persistence model**
   - JPA entities include `User`, `Session`, `Role`, `AuditLog`, and `Metrics`.
   - Repositories (`UserRepository`, `SessionRepository`, `AuditLogRepository`, `MetricsRepository`) provide database access.
   - The database is intended to be **MySQL**, and schema scripts live under `scheme/schema.sql`, which suggests the repo is meant to be bootstrapped against a relational schema rather than an embedded store.

9. **Frontend dashboard role**
   - The frontend is a React app (`src/main.jsx`, `src/App.jsx`, styles in `src/App.css` and `src/index.css`) built to act as an **API dashboard** rather than a traditional content site.
   - It likely consumes the backend endpoints to let users test auth flows and let admins inspect audit/metrics data.
   - The README’s `API_TREE` hint indicates the UI organizes endpoints into Auth/Admin/User groups and manages token state in browser storage.

10. **End-to-end request flow**
    - A typical request flow is: browser UI → backend API → security filters → controller → service → repository → database → response.
    - For authenticated calls, the JWT is attached in the `Authorization: Bearer ...` header, validated by `JwtFilter`, and then authorization decisions are made before business logic executes.
    - Audit and metrics data are captured as side effects of the request pipeline, not as separate batch jobs.

11. **Operational behavior**
    - The backend is configured with CORS support (`CorsConfig`) so the React frontend can call it from the browser during development.
    - `PasswordConfig` implies password hashing/encoding is isolated from controller code, which is a useful architectural separation for the diagram.

12. **What to emphasize in an architecture diagram**
    - Show two main tiers: **React dashboard UI** and **Spring Boot API**.
    - Inside the backend, show the request path crossing **security filters first**, then controllers/services/repositories, with **audit/metrics persistence** as parallel side effects.
    - Show the database as the shared persistence boundary for users, sessions/tokens, audit logs, and metrics.
    - Highlight that admin endpoints are not just business endpoints; they are also the consumers of the observability subsystem.

Main entry points: [`src/App.jsx`](https://github.com/chandru2002-2/corex-project/blob/main/src/App.jsx) (React dashboard), [`backend/src/main/java/com/corex/service/AuthService.java`](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/service/AuthService.java) (Auth service), [`backend/src/main/java/com/corex/config/SecurityConfig.java`](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/config/SecurityConfig.java) (Security config), [`backend/src/main/java/com/corex/repository/AuditLogRepository.java`](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/AuditLogRepository.java) (Audit repo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui["React dashboard<br/>React SPA<br/>[App.jsx]"]
  node_ui_bootstrap["App entry<br/>React entry<br/>[main.jsx]"]
  node_ui_styles["Styles<br/>CSS<br/>[App.css]"]
end

subgraph group_backend["Backend"]
  node_app["Corex app<br/>Spring Boot"]
  node_cors["CORS config<br/>web config<br/>[CorsConfig.java]"]
  node_password["Password config<br/>security config"]
  node_security["Security config<br/>Spring Security"]
  node_jwt_filter["JWT filter<br/>auth filter<br/>[JwtFilter.java]"]
  node_metrics_filter["Metrics filter<br/>observability filter<br/>[MetricsFilter.java]"]
  node_audit_filter["Audit filter<br/>[AuditFilter.java]"]
  node_auth_controller["Auth API<br/>controller"]
  node_audit_controller["Audit API<br/>controller"]
  node_metrics_controller["Metrics API<br/>controller"]
  node_role_test_controller["Role test<br/>protected controller"]
  node_auth_service["Auth service<br/>business service<br/>[AuthService.java]"]
  node_jwt_util["JWT util<br/>token utility<br/>[JwtUtil.java]"]
  node_scheduler["Scheduler<br/>background service"]
  node_user_repo[("User repo")]
  node_session_repo[("Session repo")]
  node_audit_repo[("Audit repo")]
  node_metrics_repo[("Metrics repo")]
end

subgraph group_data["Persistence"]
  node_schema[("MySQL schema<br/>relational schema<br/>[schema.sql]")]
end

node_ui_bootstrap -->|"mounts"| node_ui
node_ui -->|"calls"| node_auth_controller
node_ui -->|"calls"| node_audit_controller
node_ui -->|"calls"| node_metrics_controller
node_ui -->|"calls"| node_role_test_controller
node_cors -.->|"permits"| node_ui
node_app -->|"loads"| node_cors
node_app -->|"loads"| node_password
node_app -->|"loads"| node_security
node_security -->|"adds"| node_jwt_filter
node_security -->|"adds"| node_metrics_filter
node_security -->|"adds"| node_audit_filter
node_jwt_filter -->|"uses"| node_jwt_util
node_jwt_filter -.->|"protects"| node_auth_controller
node_metrics_filter -->|"records"| node_metrics_repo
node_audit_filter -->|"records"| node_audit_repo
node_auth_controller -->|"delegates"| node_auth_service
node_auth_service -->|"uses"| node_user_repo
node_auth_service -->|"uses"| node_session_repo
node_auth_service -->|"issues"| node_jwt_util
node_auth_service -->|"uses"| node_password
node_audit_controller -->|"reads"| node_audit_repo
node_metrics_controller -->|"reads"| node_metrics_repo
node_role_test_controller -.->|"gated by"| node_security
node_user_repo -->|"maps to"| node_schema
node_session_repo -->|"maps to"| node_schema
node_audit_repo -->|"maps to"| node_schema
node_metrics_repo -->|"maps to"| node_schema
node_scheduler -.->|"maintains"| node_audit_repo
node_scheduler -.->|"maintains"| node_metrics_repo

click node_ui "https://github.com/chandru2002-2/corex-project/blob/main/src/App.jsx"
click node_ui_bootstrap "https://github.com/chandru2002-2/corex-project/blob/main/src/main.jsx"
click node_ui_styles "https://github.com/chandru2002-2/corex-project/blob/main/src/App.css"
click node_app "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/CorexApplication.java"
click node_cors "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/config/CorsConfig.java"
click node_password "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/config/PasswordConfig.java"
click node_security "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/config/SecurityConfig.java"
click node_jwt_filter "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/security/JwtFilter.java"
click node_metrics_filter "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/security/MetricsFilter.java"
click node_audit_filter "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/security/AuditFilter.java"
click node_auth_controller "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/controller/AuthController.java"
click node_audit_controller "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/controller/AuditController.java"
click node_metrics_controller "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/controller/MetricsController.java"
click node_role_test_controller "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/controller/RoleTestController.java"
click node_auth_service "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/service/AuthService.java"
click node_jwt_util "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/util/JwtUtil.java"
click node_scheduler "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/service/SchedulerService.java"
click node_user_repo "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/UserRepository.java"
click node_session_repo "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/SessionRepository.java"
click node_audit_repo "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/AuditLogRepository.java"
click node_metrics_repo "https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/MetricsRepository.java"
click node_schema "https://github.com/chandru2002-2/corex-project/blob/main/scheme/schema.sql"

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_ui,node_ui_bootstrap,node_ui_styles toneBlue
class node_app,node_cors,node_password,node_security,node_jwt_filter,node_metrics_filter,node_audit_filter,node_auth_controller,node_audit_controller,node_metrics_controller,node_role_test_controller,node_auth_service,node_jwt_util,node_scheduler,node_user_repo,node_session_repo,node_audit_repo,node_metrics_repo toneAmber
class node_schema toneMint
```

## Components

### Frontend

React dashboard UI at the repository root.

- [React dashboard](https://github.com/chandru2002-2/corex-project/blob/main/src/App.jsx): React SPA · Browser UI for auth flows and admin telemetry views. · `src/App.jsx`
- [App entry](https://github.com/chandru2002-2/corex-project/blob/main/src/main.jsx): React entry · Frontend bootstrap and app mounting. · `src/main.jsx`
- [Styles](https://github.com/chandru2002-2/corex-project/blob/main/src/App.css): CSS · Shared UI styling for the dashboard. · `src/App.css`

### Backend

Spring Boot API and layered application code.

- [Corex app](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/CorexApplication.java): Spring Boot · Backend application bootstrap and runtime entrypoint. · `backend/src/main/java/com/corex/CorexApplication.java`
- [CORS config](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/config/CorsConfig.java): web config · Allows the React UI to call the API from the browser. · `backend/src/main/java/com/corex/config/CorsConfig.java`
- [Password config](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/config/PasswordConfig.java): security config · Centralized password hashing and encoding setup. · `backend/src/main/java/com/corex/config/PasswordConfig.java`
- [Security config](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/config/SecurityConfig.java): Spring Security · Defines public auth routes, protected routes, and role boundaries. · `backend/src/main/java/com/corex/config/SecurityConfig.java`
- [JWT filter](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/security/JwtFilter.java): auth filter · Validates bearer tokens and populates the security context. · `backend/src/main/java/com/corex/security/JwtFilter.java`
- [Metrics filter](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/security/MetricsFilter.java): observability filter · Records request timing and usage signals. · `backend/src/main/java/com/corex/security/MetricsFilter.java`
- [Audit filter](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/security/AuditFilter.java): audit filter · Captures request audit events as part of the pipeline. · `backend/src/main/java/com/corex/security/AuditFilter.java`
- [Auth API](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/controller/AuthController.java): controller · Login, registration, admin creation, refresh, and logout endpoints. · `backend/src/main/java/com/corex/controller/AuthController.java`
- [Audit API](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/controller/AuditController.java): controller · Admin-facing access to collected audit records. · `backend/src/main/java/com/corex/controller/AuditController.java`
- [Metrics API](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/controller/MetricsController.java): controller · Admin-facing access to collected usage metrics. · `backend/src/main/java/com/corex/controller/MetricsController.java`
- [Role test](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/controller/RoleTestController.java): protected controller · Protected endpoint used to validate role-based access control. · `backend/src/main/java/com/corex/controller/RoleTestController.java`
- [Auth service](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/service/AuthService.java): business service · Coordinates authentication, user setup, and token lifecycle. · `backend/src/main/java/com/corex/service/AuthService.java`
- [JWT util](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/util/JwtUtil.java): token utility · Encodes and validates JWTs used for stateless authentication. · `backend/src/main/java/com/corex/util/JwtUtil.java`
- [Scheduler](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/service/SchedulerService.java): background service · Backend scheduled work and maintenance tasks. · `backend/src/main/java/com/corex/service/SchedulerService.java`
- [User repo](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/UserRepository.java): repository · Persistence access for users and auth-related lookups. · `backend/src/main/java/com/corex/repository/UserRepository.java`
- [Session repo](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/SessionRepository.java): repository · Persistence access for session or token-tracking records. · `backend/src/main/java/com/corex/repository/SessionRepository.java`
- [Audit repo](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/AuditLogRepository.java): repository · Persistence access for audit log records. · `backend/src/main/java/com/corex/repository/AuditLogRepository.java`
- [Metrics repo](https://github.com/chandru2002-2/corex-project/blob/main/backend/src/main/java/com/corex/repository/MetricsRepository.java): repository · Persistence access for request metrics records. · `backend/src/main/java/com/corex/repository/MetricsRepository.java`

### Persistence

Relational schema and shared database-backed state.

- [MySQL schema](https://github.com/chandru2002-2/corex-project/blob/main/scheme/schema.sql): relational schema · Database schema bootstrap for the backend data model. · `scheme/schema.sql`

## Connections

- App entry → React dashboard: mounts · Bootstraps the React dashboard.
- React dashboard → Auth API: calls · Dashboard invokes authentication endpoints.
- React dashboard → Audit API: calls · Dashboard can view audit data through the API.
- React dashboard → Metrics API: calls · Dashboard can view metrics data through the API.
- React dashboard → Role test: calls · Dashboard may exercise protected role-gated routes.
- CORS config → React dashboard: permits · Enables browser access from the frontend origin.
- Corex app → CORS config: loads · Application wires web configuration.
- Corex app → Password config: loads · Application wires security support.
- Corex app → Security config: loads · Application enables Spring Security configuration.
- Security config → JWT filter: adds · Security chain includes JWT authentication.
- Security config → Metrics filter: adds · Security chain includes request metrics capture.
- Security config → Audit filter: adds · Security chain includes request auditing.
- JWT filter → JWT util: uses · Filter delegates token validation and parsing.
- JWT filter → Auth API: protects · Authenticated requests reach controllers after token validation.
- Metrics filter → Metrics repo: records · Metrics filter persists usage statistics.
- Audit filter → Audit repo: records · Audit filter persists request audit events.
- Auth API → Auth service: delegates · Controller passes login and registration flows to service logic.
- Auth service → User repo: uses · Service reads and writes users.
- Auth service → Session repo: uses · Service tracks login or refresh state.
- Auth service → JWT util: issues · Service creates and validates tokens.
- Auth service → Password config: uses · Service relies on password encoding.
- Audit API → Audit repo: reads · Admin endpoint queries audit history.
- Metrics API → Metrics repo: reads · Admin endpoint queries request metrics.
- Role test → Security config: gated by · Protected controller demonstrates role-based access control.
- User repo → MySQL schema: maps to · Repository persists user entities in the relational schema.
- Session repo → MySQL schema: maps to · Repository persists session records in the relational schema.
- Audit repo → MySQL schema: maps to · Repository persists audit logs in the relational schema.
- Metrics repo → MySQL schema: maps to · Repository persists metrics in the relational schema.
- Scheduler → Audit repo: maintains · Background work can coordinate with persisted telemetry.
- Scheduler → Metrics repo: maintains · Background work can coordinate with persisted metrics.