# hilalinabil/telecom_application architecture

> Architecture diagram of the GitHub repository hilalinabil/telecom_application, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hilalinabil/telecom_application
- Repository: https://github.com/hilalinabil/telecom_application

## Overview

1. This repository is a full-stack telecom network management system split into two clear deployable parts: a Spring Boot backend at the repository root and a React frontend under `frontend/`. The backend exposes JSON APIs; the frontend is a single-page app that consumes them.

2. The backend follows a classic layered architecture: `controllers` handle HTTP requests, `services` contain business logic, `repositories` access MongoDB, and `models` define persisted domain objects. DTOs sit between API payloads and internal models, which keeps the transport layer separate from the persistence model.

3. The core domain is telecom infrastructure management. The main entity families are `Datacenter`, `Repartiteur`/OLT, `Splitter`, `ClientBox`, `Client`, `FibrePath`, `Equipement`, and `GeoPoint`. These map directly to the network hierarchy described in the README: datacenter → distribution node → splitter → client box → customer.

4. Persistence is MongoDB-based, not relational. The repository layer is made of Spring Data-style repositories for each aggregate. Domain enums such as `Role`, `UserStatus`, `NetworkStatus`, `FibreStatus`, and others encode controlled lifecycle and classification values across the system.

5. Authentication and authorization are a dedicated subsystem. Backend security is implemented with Spring Security, JWT, a custom user-details service, a JWT filter, and a security config. Users authenticate with a matricule/password pair, and role-based access is enforced for `SUPER_ADMIN`, `ADMIN`, and `TECHNICIAN`.

6. User administration is tightly controlled. There is no public registration flow; user creation is performed by authorized admins according to the role hierarchy. The backend includes dedicated auth and user controllers/services, plus password-change and user-creation DTOs.

7. The frontend is organized around routes and feature pages rather than a single generic screen. `pages/` contains views like dashboards, asset management screens, login, profile, logs, and map pages. `components/` holds reusable UI pieces such as layout, header, sidebar, protected route guard, data table, and network map.

8. Shared frontend state is centralized in React contexts. `AuthContext` manages login/session state, while `ThemeContext` handles UI theming. Route protection is enforced on the client with `ProtectedRoute`, matching the backend’s JWT/role model.

9. The frontend data-access pattern is hook-based. Custom hooks such as `useCrud`, `useDashboard`, and `useNetworkMap` encapsulate API calls, filtering, and view-specific data loading. All HTTP traffic goes through `services/api.js`, which is the frontend’s main boundary to the backend API.

10. Geographic and topology visualization is a distinct subsystem. `NetworkMap` and `MapPage` use Leaflet/OpenStreetMap to render nodes and fiber routes. The backend’s `GeoPoint` and `FibrePath` resources supply the location and path data used for map rendering.

11. Dashboarding is another cross-cutting feature. The backend has a `DashboardController` and `DashboardService` that aggregate infrastructure and capacity metrics, and the frontend dashboard pages consume those summaries to show totals, occupancy, and network status indicators.

12. Auditability is built into the data model and operations. There is an `ActivityLog` model/repository/service/controller for tracing actions, and the README indicates record metadata such as `CreatedBy`, `CreatedAt`, and `UpdatedAt`. This makes operational history part of the architecture, not an afterthought.

13. Error handling and input validation are centralized on the backend. Request DTOs define the accepted API contract, while `GlobalExceptionHandler` and `ApiException` provide consistent error responses. This helps keep controllers thin and predictable.

14. Deployment/runtime tooling also shapes the architecture: the backend is built with Maven and Spring Boot 3, while the frontend uses Vite and is packaged with a Dockerfile plus Nginx for static serving. The repo includes Maven wrapper files and a Spring Boot test class, indicating standard Java service build/test workflows.

15. For an architecture diagram, the important boundaries are: browser UI → React app → authenticated API calls → Spring controllers → services → MongoDB, with a separate map/visualization path and a shared security boundary wrapping all protected resources.

Main entry points: [`src/main/java/com/example/telecom_network/controllers`](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/controllers) (Controllers), [`src/main/java/com/example/telecom_network/services`](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/services) (Services), [`frontend/src/pages`](https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/pages) (Pages), [`src/main/java/com/example/telecom_network/security`](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/security) (Security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_app(("Spring Boot App<br/>entrypoint"))
  node_backend_config["Config"]
  node_backend_security["Security<br/>auth stack"]
  node_backend_exception["Errors<br/>exception layer"]
  node_controllers["Controllers<br/>HTTP API"]
  node_services["Services<br/>business layer"]
  node_repositories["Repositories<br/>Mongo access"]
  node_models[("Domain Models<br/>persistence model")]
  node_dtos["DTOs<br/>api contract"]
  node_network_core[("Network Core<br/>telecom domain")]
end

subgraph group_frontend["Frontend"]
  node_frontend_shell(("React App<br/>spa shell<br/>[App.jsx]"))
  node_frontend_layout["UI Layout<br/>ui components"]
  node_frontend_pages["Pages<br/>route views"]
  node_frontend_contexts["Contexts<br/>client state"]
  node_frontend_hooks["Hooks"]
  node_frontend_api["API Client<br/>http client<br/>[api.js]"]
  node_map_analytics["Map & Dashboard<br/>visualization<br/>[MapPage.jsx]"]
end

node_auth_flow{{"Auth Flow<br/>security boundary"}}

node_app -->|"starts with"| node_backend_config
node_app -->|"exposes"| node_controllers
node_backend_config -->|"wires"| node_backend_security
node_controllers -->|"accepts/returns"| node_dtos
node_controllers -->|"delegates to"| node_services
node_services -->|"reads/writes"| node_repositories
node_repositories -->|"maps"| node_models
node_services -->|"operates on"| node_models
node_services -->|"raises"| node_backend_exception
node_controllers -->|"handled by"| node_backend_exception
node_controllers -->|"protected by"| node_backend_security
node_backend_security -->|"enforces"| node_auth_flow
node_frontend_shell -->|"composes"| node_frontend_layout
node_frontend_shell -->|"routes to"| node_frontend_pages
node_frontend_pages -->|"uses"| node_frontend_contexts
node_frontend_pages -->|"loads data with"| node_frontend_hooks
node_frontend_hooks -->|"calls"| node_frontend_api
node_frontend_layout -->|"guards"| node_auth_flow
node_frontend_pages -->|"includes"| node_map_analytics
node_map_analytics -->|"renders"| node_network_core
node_frontend_api -->|"consumes"| node_controllers
node_dtos -.->|"shapes"| node_network_core
node_services -->|"manages"| node_network_core

click node_app "https://github.com/hilalinabil/telecom_application/blob/main/src/main/java/com/example/telecom_network/TelecomNetworkApplication.java"
click node_backend_config "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/config"
click node_backend_security "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/security"
click node_backend_exception "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/exceptions"
click node_controllers "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/controllers"
click node_services "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/services"
click node_repositories "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/repositories"
click node_models "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/models"
click node_dtos "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/dtos"
click node_frontend_shell "https://github.com/hilalinabil/telecom_application/blob/main/frontend/src/App.jsx"
click node_frontend_layout "https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/components"
click node_frontend_pages "https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/pages"
click node_frontend_contexts "https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/context"
click node_frontend_hooks "https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/hooks"
click node_frontend_api "https://github.com/hilalinabil/telecom_application/blob/main/frontend/src/services/api.js"
click node_network_core "https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/models"
click node_map_analytics "https://github.com/hilalinabil/telecom_application/blob/main/frontend/src/pages/MapPage.jsx"

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_app,node_backend_config,node_backend_security,node_backend_exception,node_controllers,node_services,node_repositories,node_models,node_dtos,node_network_core toneBlue
class node_frontend_shell,node_frontend_layout,node_frontend_pages,node_frontend_contexts,node_frontend_hooks,node_frontend_api,node_map_analytics toneAmber
class node_auth_flow toneNeutral
```

## Components

### Backend

Spring Boot API, domain, persistence, and security

- [Spring Boot App](https://github.com/hilalinabil/telecom_application/blob/main/src/main/java/com/example/telecom_network/TelecomNetworkApplication.java): entrypoint · Application bootstrap for the backend service · `src/main/java/com/example/telecom_network/TelecomNetworkApplication.java`
- [Config](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/config): boot config · Database initialization and security wiring · `src/main/java/com/example/telecom_network/config`
- [Security](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/security): auth stack · JWT authentication, user details, and request filtering · `src/main/java/com/example/telecom_network/security`
- [Errors](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/exceptions): exception layer · Centralized API exceptions and global handling · `src/main/java/com/example/telecom_network/exceptions`
- [Controllers](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/controllers): HTTP API · Request handlers for auth, assets, dashboards, users, maps, and logs · `src/main/java/com/example/telecom_network/controllers`
- [Services](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/services): business layer · Business logic for telecom assets, users, dashboards, and auditing · `src/main/java/com/example/telecom_network/services`
- [Repositories](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/repositories): Mongo access · Spring Data repositories for domain aggregates · `src/main/java/com/example/telecom_network/repositories`
- [Domain Models](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/models): persistence model · MongoDB-backed telecom entities and enums · `src/main/java/com/example/telecom_network/models`
- [DTOs](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/dtos): api contract · Request and response objects separating transport from persistence · `src/main/java/com/example/telecom_network/dtos`
- [Network Core](https://github.com/hilalinabil/telecom_application/tree/main/src/main/java/com/example/telecom_network/models): telecom domain · Datacenter, repartiteur, splitter, client box, client, equipment, fiber path, and geo point management · `src/main/java/com/example/telecom_network/models`

### Frontend

React SPA, UI composition, and API consumption

- [React App](https://github.com/hilalinabil/telecom_application/blob/main/frontend/src/App.jsx): spa shell · Frontend entry and routing shell · `frontend/src/App.jsx`
- [UI Layout](https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/components): ui components · Shared layout, navigation, table, protected route, and map components · `frontend/src/components`
- [Pages](https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/pages): route views · Dashboard, asset management, auth, profile, logs, and map screens · `frontend/src/pages`
- [Contexts](https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/context): client state · Authentication and theme state shared across the app · `frontend/src/context`
- [Hooks](https://github.com/hilalinabil/telecom_application/tree/main/frontend/src/hooks): data hooks · Reusable CRUD, dashboard, and network map data-loading hooks · `frontend/src/hooks`
- [API Client](https://github.com/hilalinabil/telecom_application/blob/main/frontend/src/services/api.js): http client · Single boundary for all frontend HTTP calls · `frontend/src/services/api.js`
- [Map & Dashboard](https://github.com/hilalinabil/telecom_application/blob/main/frontend/src/pages/MapPage.jsx): visualization · Topology visualization and aggregated operational metrics · `frontend/src/pages/MapPage.jsx`

### Other components

- **Auth Flow**: security boundary · Login, JWT session state, and route protection on client and server

## Connections

- Spring Boot App → Config: starts with · Bootstraps configuration and initialization
- Spring Boot App → Controllers: exposes · Launches the HTTP API surface
- Config → Security: wires · Registers the security filter chain and related beans
- Controllers → DTOs: accepts/returns · Uses request and response contracts
- Controllers → Services: delegates to · Keeps request handling thin
- Services → Repositories: reads/writes · Persists and loads aggregate data
- Repositories → Domain Models: maps · Stores domain entities in MongoDB
- Services → Domain Models: operates on · Contains core telecom rules and state transitions
- Services → Errors: raises · Converts business failures into API errors
- Controllers → Errors: handled by · Produces consistent error responses
- Controllers → Security: protected by · Secured endpoints require authenticated roles
- Security → Auth Flow: enforces · JWT authentication and role-based access
- React App → UI Layout: composes · Builds the application frame
- React App → Pages: routes to · Maps URLs to feature screens
- Pages → Contexts: uses · Consumes auth and theme state
- Pages → Hooks: loads data with · Fetches and filters view-specific data
- Hooks → API Client: calls · All backend requests go through one client
- UI Layout → Auth Flow: guards · Protected routes and session-aware UI
- Pages → Map & Dashboard: includes · Dashboard and map views present network status
- Map & Dashboard → Network Core: renders · Visualizes topology and fiber routes from domain data
- API Client → Controllers: consumes · Frontend talks to backend JSON endpoints
- DTOs → Network Core: shapes · API payloads mirror telecom resources
- Services → Network Core: manages · Implements the core network management workflows