# hazem897/ooredoo-portal-web architecture

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

- Interactive diagram: https://gitdiagram.com/hazem897/ooredoo-portal-web
- Repository: https://github.com/hazem897/ooredoo-portal-web

## Overview

1. **Vue d’ensemble**
   - Le dépôt contient une application de portail d’entreprise séparée en deux grands blocs : un **backend Node.js/Express** et un **frontend React/Vite**.
   - Le frontend est l’interface utilisateur ; le backend expose une API REST et concentre l’authentification, les règles métier, l’accès à MySQL, les e-mails et les tâches automatisées.

2. **Front-end React comme couche de présentation**
   - Le client vit dans `frontend/src` et est structuré par **pages**, **composants**, **layouts**, **contexts** et **services**.
   - `main.tsx` démarre l’application, `App.tsx` porte le routage, et les pages principales couvrent login, dashboard, profil, utilisateurs, alertes, notifications, journaux, thèmes et Power BI.

3. **Gestion d’état et contrôle d’accès côté client**
   - `AuthContext` porte l’état d’authentification global, tandis que `LanguageContext` gère l’i18n.
   - `RouteProtegee` et `RouteAdmin` servent de frontières d’accès dans l’UI : elles bloquent les vues selon le statut de connexion ou le rôle.
   - `MainLayout`, `Sidebar`, `Navbar` et `MobileBottomNav` composent le cadre de navigation persistante.

4. **Couche d’appel API côté front**
   - `frontend/src/utils/api.jsx` et les services dédiés comme `dashboardService.js` et `alertesService.js` centralisent les appels HTTP.
   - Le README indique que cette couche injecte le token Bearer, donc le front ne parle pas directement à la base de données ; il passe uniquement par l’API backend.

5. **Backend Express organisé en MVC**
   - Le backend suit une structure proche du MVC : `routes` définissent les endpoints, `controllers` portent la logique métier, `middleware` gère les interceptions transverses, et `services` encapsulent les intégrations externes.
   - Les routes principales sont `auth`, `users`, `dashboard`, `tickets`, `alertes` et `logs`, ce qui reflète les domaines fonctionnels du portail.

6. **Authentification et autorisation**
   - L’authentification est centralisée dans `authController.js` et protégée par `middleware/auth.js`.
   - Le projet combine plusieurs mécanismes : **bcryptjs** pour les mots de passe, **JWT** pour les sessions sans état, et **OTP** pour les validations sensibles ou la récupération de compte.
   - Le flux d’accès est renforcé par une validation manuelle des nouveaux comptes et par des contrôles de rôle côté serveur et côté client.

7. **Persistance des données et schéma MySQL**
   - `config/db.js` relie l’API à **MySQL** ; `database.sql` et les scripts de migration/synchronisation montrent que le schéma est un élément important de l’architecture.
   - Les contrôleurs lisent et écrivent dans la base pour les utilisateurs, tickets, alertes, logs et tableaux de bord.
   - Le dossier `uploads/profiles` indique aussi une persistance de fichiers pour les photos de profil, séparée de la base relationnelle.

8. **Services transverses : e-mail, reporting et planification**
   - `services/emailService.js` gère l’envoi d’e-mails transactionnels via `config/nodemailer.js`.
   - `services/reportService.js` et `cronScheduler.js` introduisent une couche d’automatisation : génération planifiée de rapports, export PDF/CSV/Excel et envoi périodique.
   - Cette partie fonctionne comme un sous-système asynchrone distinct du flux web classique.

9. **Journalisation et sécurité d’exécution**
   - `middleware/logger.js` et les contrôleurs de logs forment le sous-système de traçabilité : accès, activités techniques et événements sensibles sont enregistrés.
   - Plusieurs utilitaires renforcent la sécurité applicative : génération d’OTP, validation d’entrées, gestion de mots de passe, et scripts de contrôle/audit.
   - Le dépôt contient aussi de nombreux fichiers de test et de diagnostic backend, signe d’une couche d’exploitation et de vérification importante.

10. **Fonctionnalités métier visibles dans l’UI**
   - Les pages `Dashboard`, `Utilisateurs`, `Alertes`, `Notifications`, `Journalisation`, `Profil` et `Themes` indiquent un portail orienté gestion et supervision.
   - La page `PowerBI` suggère une intégration de tableaux de bord analytiques externes ou embarqués.
   - La présence de composants comme `SecurityBadge` et `PWAInstaller` montre que l’interface expose aussi des éléments liés à la sécurité et à l’installabilité.

11. **PWA, responsive design et expérience terrain**
   - Le frontend inclut `vite.config.ts`, un manifeste/PWA via `public` et des artefacts `dev-dist`, ce qui confirme une application web installable.
   - Les layouts mobile, la sidebar responsive et les styles dédiés indiquent une forte priorité à l’usage sur desktop et mobile.
   - Les contexts, hooks et CSS du client servent surtout à maintenir une expérience homogène, multilingue et adaptable, sans changer la logique métier centrale.

12. **Ce que l’architecture sépare clairement**
   - **Présentation** : React/Vite, navigation, thèmes, i18n, PWA.
   - **API métier** : Express, contrôleurs, routes, middleware.
   - **Données** : MySQL + fichiers de profil.
   - **Intégrations externes** : SMTP/Nodemailer, génération de rapports, éventuel Power BI.
   - **Automatisation** : cron et scripts de migration/test.

Main entry points: [`backend/controllers/authController.js`](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/controllers/authController.js) (Auth flow), [`backend/controllers/userController.js`](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/controllers/userController.js) (Domain controllers), [`frontend/src/main.tsx`](https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/main.tsx) (App shell), [`backend/routes/auth.js`](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/routes/auth.js) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_shell["App shell<br/>React entry/routing<br/>[main.tsx]"]
  node_frontend_layout["Main layout<br/>UI shell<br/>[MainLayout.jsx]"]
  node_frontend_access["Access guards<br/>route protection<br/>[RouteProtegee.jsx]"]
  node_frontend_state["Client state<br/>contexts<br/>[AuthContext.jsx]"]
  node_frontend_api["API client<br/>HTTP layer<br/>[api.jsx]"]
  node_frontend_pages["Portal pages<br/>views<br/>[Dashboard.jsx]"]
  node_frontend_pwa["PWA UI<br/>installable UI<br/>[PWAInstaller.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_server["Express server<br/>API entry<br/>[server.js]"]
  node_backend_routes["API routes<br/>endpoint map<br/>[auth.js]"]
  node_backend_auth["Auth flow<br/>security<br/>[authController.js]"]
  node_backend_domain["Domain controllers<br/>business logic<br/>[userController.js]"]
  node_backend_middleware["Middleware<br/>cross-cutting<br/>[auth.js]"]
  node_backend_services["Backend services<br/>integrations<br/>[emailService.js]"]
  node_backend_config["Backend config<br/>runtime config<br/>[db.js]"]
  node_backend_scheduler["Cron jobs<br/>automation<br/>[cronScheduler.js]"]
end

subgraph group_data["Data"]
  node_data_mysql[("MySQL<br/>relational store<br/>[database.sql]")]
  node_data_uploads["Profile files<br/>file storage"]
end

subgraph group_ops["Automation"]
  node_ops_migrations["Schema scripts<br/>maintenance<br/>[database.sql]"]
  node_ops_tests["Diagnostics<br/>verification<br/>[test_login.js]"]
end

node_frontend_shell -->|"renders"| node_frontend_layout
node_frontend_shell -->|"protects"| node_frontend_access
node_frontend_shell -->|"shares state"| node_frontend_state
node_frontend_layout -->|"hosts"| node_frontend_pages
node_frontend_state -->|"feeds"| node_frontend_pages
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_server
node_frontend_pwa -->|"enhances"| node_frontend_shell
node_backend_server -->|"mounts"| node_backend_routes
node_backend_routes -->|"dispatches"| node_backend_auth
node_backend_routes -->|"dispatches"| node_backend_domain
node_backend_auth -->|"uses"| node_backend_middleware
node_backend_domain -->|"uses"| node_backend_middleware
node_backend_auth -->|"uses"| node_backend_config
node_backend_domain -->|"persists"| node_data_mysql
node_backend_auth -->|"persists"| node_data_mysql
node_backend_services -->|"uses"| node_backend_config
node_backend_services -->|"drives"| node_backend_scheduler
node_backend_scheduler -->|"invokes"| node_backend_services
node_backend_domain -->|"reads/writes"| node_data_uploads
node_ops_migrations -->|"changes"| node_data_mysql
node_ops_tests -.->|"verifies"| node_backend_server

click node_frontend_shell "https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/main.tsx"
click node_frontend_layout "https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/layouts/MainLayout.jsx"
click node_frontend_access "https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/components/RouteProtegee.jsx"
click node_frontend_state "https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_api "https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/utils/api.jsx"
click node_frontend_pages "https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/pages/Dashboard/Dashboard.jsx"
click node_frontend_pwa "https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/components/PWAInstaller.jsx"
click node_backend_server "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/server.js"
click node_backend_routes "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/routes/auth.js"
click node_backend_auth "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/controllers/authController.js"
click node_backend_domain "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/controllers/userController.js"
click node_backend_middleware "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/middleware/auth.js"
click node_backend_services "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/services/emailService.js"
click node_backend_config "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/config/db.js"
click node_backend_scheduler "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/cronScheduler.js"
click node_data_mysql "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/database.sql"
click node_data_uploads "https://github.com/hazem897/ooredoo-portal-web/tree/main/backend/uploads/profiles"
click node_ops_migrations "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/scripts/database.sql"
click node_ops_tests "https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/test_login.js"

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_frontend_shell,node_frontend_layout,node_frontend_access,node_frontend_state,node_frontend_api,node_frontend_pages,node_frontend_pwa toneBlue
class node_backend_server,node_backend_routes,node_backend_auth,node_backend_domain,node_backend_middleware,node_backend_services,node_backend_config,node_backend_scheduler toneAmber
class node_data_mysql,node_data_uploads toneMint
class node_ops_migrations,node_ops_tests toneRose
```

## Components

### Frontend

React/Vite presentation layer and client-side state

- [App shell](https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/main.tsx): React entry/routing · Bootstraps the SPA and defines the client-side route structure · `frontend/src/main.tsx`
- [Main layout](https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/layouts/MainLayout.jsx): UI shell · Persistent navigation frame for desktop and mobile views · `frontend/src/layouts/MainLayout.jsx`
- [Access guards](https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/components/RouteProtegee.jsx): route protection · Blocks protected and admin-only views in the UI · `frontend/src/components/RouteProtegee.jsx`
- [Client state](https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/context/AuthContext.jsx): contexts · Global auth and language state shared across the app · `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/utils/api.jsx): HTTP layer · Centralized browser API calls with bearer token injection · `frontend/src/utils/api.jsx`
- [Portal pages](https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/pages/Dashboard/Dashboard.jsx): views · Business screens for dashboard, users, alerts, logs, profile, themes, notifications, Power BI, login, and recovery · `frontend/src/pages/Dashboard/Dashboard.jsx`
- [PWA UI](https://github.com/hazem897/ooredoo-portal-web/blob/main/frontend/src/components/PWAInstaller.jsx): installable UI · Installability, responsive navigation, and offline-ready frontend assets · `frontend/src/components/PWAInstaller.jsx`

### Backend

Express API, business rules, and integrations

- [Express server](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/server.js): API entry · Starts the Node.js service and wires routes and middleware · `backend/server.js`
- [API routes](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/routes/auth.js): endpoint map · HTTP boundaries for auth, users, dashboard, tickets, alerts, and logs · `backend/routes/auth.js`
- [Auth flow](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/controllers/authController.js): security · Login, JWT session handling, password checks, OTP, and account validation · `backend/controllers/authController.js`
- [Domain controllers](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/controllers/userController.js): business logic · User, dashboard, ticket, alert, and log operations · `backend/controllers/userController.js`
- [Middleware](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/middleware/auth.js): cross-cutting · Authentication, logging, and request interception · `backend/middleware/auth.js`
- [Backend services](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/services/emailService.js): integrations · Email delivery and report generation services · `backend/services/emailService.js`
- [Backend config](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/config/db.js): runtime config · Database and SMTP configuration used by the API · `backend/config/db.js`
- [Cron jobs](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/cronScheduler.js): automation · Scheduled report and maintenance execution outside the request cycle · `backend/cronScheduler.js`

### Data

MySQL schema and file persistence

- [MySQL](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/database.sql): relational store · Primary persistent store for users, tickets, alerts, logs, and dashboard data · `backend/database.sql`
- [Profile files](https://github.com/hazem897/ooredoo-portal-web/tree/main/backend/uploads/profiles): file storage · Uploaded profile assets stored separately from the database · `backend/uploads/profiles`

### Automation

Scheduled jobs, reporting, and maintenance scripts

- [Schema scripts](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/scripts/database.sql): maintenance · Database migration, import, and verification scripts · `backend/scripts/database.sql`
- [Diagnostics](https://github.com/hazem897/ooredoo-portal-web/blob/main/backend/test_login.js): verification · Ad hoc API, DB, SMTP, and login checks used for operational validation · `backend/test_login.js`

## Connections

- App shell → Main layout: renders · The app mounts its persistent shell and layout
- App shell → Access guards: protects · Routes are wrapped by access guards
- App shell → Client state: shares state · Contexts provide auth and language state to the UI
- Main layout → Portal pages: hosts · Layout frames the portal pages
- Client state → Portal pages: feeds · Pages read auth and locale state
- Portal pages → API client: calls · Views fetch and mutate data through the API client
- API client → Express server: requests · Client HTTP traffic targets the backend API
- PWA UI → App shell: enhances · Installable and responsive behavior augments the SPA
- Express server → API routes: mounts · The server exposes the route modules
- API routes → Auth flow: dispatches · Auth endpoints are handled by the auth controller
- API routes → Domain controllers: dispatches · Business endpoints are routed to domain controllers
- Auth flow → Middleware: uses · Auth is protected by middleware checks
- Domain controllers → Middleware: uses · Domain endpoints share logging and auth interception
- Auth flow → Backend config: uses · Authentication depends on DB and SMTP configuration
- Domain controllers → MySQL: persists · Controllers read and write core application data
- Auth flow → MySQL: persists · Credential and account state live in MySQL
- Backend services → Backend config: uses · Services depend on mail and database configuration
- Backend services → Cron jobs: drives · Scheduled tasks trigger reporting and delivery flows
- Cron jobs → Backend services: invokes · Cron jobs run service-level automation
- Domain controllers → Profile files: reads/writes · Profile-related features interact with file storage
- Schema scripts → MySQL: changes · Scripts evolve and repair the database schema
- Diagnostics → Express server: verifies · Operational scripts exercise the API and integrations