# chaima-touj/stage-flow architecture

> Architecture diagram of the GitHub repository chaima-touj/stage-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chaima-touj/stage-flow
- Repository: https://github.com/chaima-touj/stage-flow

## Overview

1. **What this repo is**
   - StageFlow is a full-stack platform centered on training programs (“formations”), job/placement offers, applications, interviews, messaging, notifications, and an AI assistant.
   - The repository is split cleanly into a **React frontend** and a **Node/Express backend**, each with its own package and runtime boundary.

2. **Frontend shell**
   - The `client/` app is a **Vite-powered React SPA**.
   - `src/main.jsx` and `src/App.jsx` anchor the app, while `index.css` and per-page CSS files indicate a mostly component-scoped styling model rather than a large shared design system.

3. **Frontend structure by feature**
   - UI is organized into feature pages under `src/pages/`, with distinct areas for:
     - public marketing/discovery: `LandingPage`, `FormationsPage`, `OffersPage`, `PublicOfferDetail`
     - authentication: `Login`, `Register`, `VerifyEmail`
     - user workspace: dashboard, profile, settings, messages, notifications, interviews, applications, AI assistant
   - This suggests the app has both **public-facing** and **authenticated** experiences.

4. **Frontend layout and shared components**
   - Reusable UI is factored into `src/components/common/` and `src/components/layout/`.
   - Layout components like `Sidebar`, `Topbar`, `DashboardLayout`, and `NotificationPanel` imply a persistent authenticated shell around most dashboard pages.
   - Shared widgets such as `FileUpload`, `CoursePreviewModal`, `SectionCard`, and language flag components indicate repeated interaction patterns across pages.

5. **Frontend state and cross-cutting concerns**
   - `AuthContext`, `LangContext`, and `ThemeContext` are the main client-side global state boundaries.
   - Internationalization is built in through `src/i18n/` with `en`, `fr`, and `ar` locale files, so language is a first-class concern.
   - The `src/services/` layer is the frontend’s main backend integration point; it centralizes API calls per domain instead of calling endpoints directly from components.

6. **Backend application shape**
   - The `server/` side follows a classic **controller / route / model** structure.
   - `routes/` define API entry points, `controllers/` hold request handling logic, `models/` represent domain entities, and `middleware/` handles auth, uploads, sanitization, and error handling.
   - `server/server.js` is the application entry, with `config/db.js` managing database connectivity.

7. **Backend domain model**
   - The backend is organized around explicit business entities:
     - users/authentication
     - formations
     - offers
     - applications
     - enrollment requests and enrollments
     - favorites
     - interviews
     - conversations and messages
     - notifications
     - documents
   - This mirrors the frontend’s feature set and indicates the backend is the source of truth for user workflow data.

8. **Important backend integrations**
   - `services/email.service.js` indicates server-side email delivery, likely used for registration, verification, or workflow notifications.
   - `services/groq.service.js` plus `controllers/ai.controller.js` show a dedicated AI integration path, separate from the rest of the CRUD flows.
   - Upload handling is isolated through `middleware/upload.middleware.js`, with stored files in `server/uploads/`.

9. **Content and seed data**
   - `server/formations/*.json` contains structured formation content, suggesting some training catalog data is file-backed or seeded from curated JSON rather than created only through the UI.
   - `seed.js`, `seed_formations.mjs`, and `migrate.js` indicate setup scripts for bootstrapping or evolving the database state.

10. **Request flow from browser to backend**
   - The typical flow is: React page/component → `client/src/services/*` API wrapper → Express route → middleware → controller → model/database.
   - For protected areas, `auth.middleware.js` and JWT utilities in `server/utils/jwt.js` enforce access control before a controller runs.

11. **Security and data hygiene boundaries**
   - `auth.middleware.js`, `sanitize.middleware.js`, and `error.middleware.js` show explicit server-side boundaries for authentication, input cleanup, and centralized failure handling.
   - This suggests the backend is designed to be the enforcement point for trust, while the frontend remains a thin interaction layer.

12. **Operational/runtime separation**
   - Client and server are independently built and run, with separate `package-lock.json` files and config files like `client/vite.config.js`.
   - `.env.example` at the repo root implies environment-driven deployment/configuration, likely for API URLs, database credentials, JWT secrets, and external service keys.

13. **Architecture summary for diagramming**
   - Draw this repo as two primary tiers:
     - **Frontend SPA**: public pages, authenticated dashboard, shared layout/components, global context, i18n, and API service wrappers
     - **Backend API**: Express routes/controllers/models, auth and upload middleware, DB access, email/AI services, and seed/migration utilities
   - The central data backbone is the backend database, with the frontend consuming it through REST-style service calls and the backend integrating external services like email and AI.

Main entry points: [`client/src/main.jsx`](https://github.com/chaima-touj/stage-flow/blob/main/client/src/main.jsx) (App shell), [`server/controllers`](https://github.com/chaima-touj/stage-flow/tree/main/server/controllers) (Controllers), [`server/routes`](https://github.com/chaima-touj/stage-flow/tree/main/server/routes) (API routes), [`client/src/components/common`](https://github.com/chaima-touj/stage-flow/tree/main/client/src/components/common) (Shared widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_client_main["App shell<br/>React entry<br/>[main.jsx]"]
  node_client_pages_public["Public pages<br/>React pages"]
  node_client_pages_auth["Auth pages<br/>React pages"]
  node_client_pages_dashboard["Dashboard pages<br/>React pages"]
  node_client_pages_workflows["Workflows<br/>React pages"]
  node_client_layout["Shell layout<br/>React layout"]
  node_client_common["Shared widgets<br/>React components"]
  node_client_context(("Client state<br/>React context"))
  node_client_i18n(("i18n<br/>localization"))
  node_client_services["API services<br/>HTTP wrappers"]
end

subgraph group_backend["Backend API"]
  node_server_entry["Server entry<br/>Express entry<br/>[server.js]"]
  node_server_routes["API routes<br/>Express routes"]
  node_server_controllers["Controllers<br/>request handlers"]
  node_server_middleware["Middleware<br/>request guards"]
  node_server_models[("Domain models<br/>data models")]
  node_server_services["External services<br/>integrations"]
  node_server_db[("Database<br/>db config<br/>[db.js]")]
  node_server_content["Formation content<br/>seed data"]
  node_server_bootstrap["Bootstrap scripts<br/>ops scripts<br/>[seed.js]"]
end

node_client_main -->|"renders"| node_client_pages_public
node_client_main -->|"renders"| node_client_pages_auth
node_client_main -->|"renders"| node_client_pages_dashboard
node_client_main -->|"renders"| node_client_pages_workflows
node_client_main -->|"uses"| node_client_layout
node_client_pages_public -->|"shares UI"| node_client_common
node_client_pages_dashboard -->|"shares UI"| node_client_common
node_client_pages_workflows -->|"shares UI"| node_client_common
node_client_context -->|"provides state"| node_client_main
node_client_i18n -->|"supports"| node_client_context
node_client_services -->|"calls"| node_server_routes
node_server_entry -->|"mounts"| node_server_routes
node_server_routes -->|"passes through"| node_server_middleware
node_server_routes -->|"dispatches"| node_server_controllers
node_server_controllers -->|"reads/writes"| node_server_models
node_server_controllers -->|"uses"| node_server_services
node_server_models -->|"persists via"| node_server_db
node_server_controllers -->|"loads"| node_server_content
node_server_bootstrap -->|"initializes"| node_server_db
node_server_middleware -.->|"guards"| node_server_services

click node_client_main "https://github.com/chaima-touj/stage-flow/blob/main/client/src/main.jsx"
click node_client_pages_public "https://github.com/chaima-touj/stage-flow/tree/main/client/src/pages"
click node_client_pages_auth "https://github.com/chaima-touj/stage-flow/tree/main/client/src/pages/auth"
click node_client_pages_dashboard "https://github.com/chaima-touj/stage-flow/tree/main/client/src/pages/dashboard"
click node_client_pages_workflows "https://github.com/chaima-touj/stage-flow/tree/main/client/src/pages"
click node_client_layout "https://github.com/chaima-touj/stage-flow/tree/main/client/src/components/layout"
click node_client_common "https://github.com/chaima-touj/stage-flow/tree/main/client/src/components/common"
click node_client_context "https://github.com/chaima-touj/stage-flow/tree/main/client/src/context"
click node_client_i18n "https://github.com/chaima-touj/stage-flow/tree/main/client/src/i18n"
click node_client_services "https://github.com/chaima-touj/stage-flow/tree/main/client/src/services"
click node_server_entry "https://github.com/chaima-touj/stage-flow/blob/main/server/server.js"
click node_server_routes "https://github.com/chaima-touj/stage-flow/tree/main/server/routes"
click node_server_controllers "https://github.com/chaima-touj/stage-flow/tree/main/server/controllers"
click node_server_middleware "https://github.com/chaima-touj/stage-flow/tree/main/server/middleware"
click node_server_models "https://github.com/chaima-touj/stage-flow/tree/main/server/models"
click node_server_services "https://github.com/chaima-touj/stage-flow/tree/main/server/services"
click node_server_db "https://github.com/chaima-touj/stage-flow/blob/main/server/config/db.js"
click node_server_content "https://github.com/chaima-touj/stage-flow/tree/main/server/formations"
click node_server_bootstrap "https://github.com/chaima-touj/stage-flow/blob/main/server/seed.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_client_main,node_client_pages_public,node_client_pages_auth,node_client_pages_dashboard,node_client_pages_workflows,node_client_layout,node_client_common,node_client_context,node_client_i18n,node_client_services toneBlue
class node_server_entry,node_server_routes,node_server_controllers,node_server_middleware,node_server_models,node_server_services,node_server_db,node_server_content,node_server_bootstrap toneAmber
```

## Components

### Frontend SPA

React/Vite client with public pages, dashboard shell, global state, and API wrappers.

- [App shell](https://github.com/chaima-touj/stage-flow/blob/main/client/src/main.jsx): React entry · Vite bootstrapping and top-level app composition. · `client/src/main.jsx`
- [Public pages](https://github.com/chaima-touj/stage-flow/tree/main/client/src/pages): React pages · Landing, formations, offers, and public offer detail views. · `client/src/pages`
- [Auth pages](https://github.com/chaima-touj/stage-flow/tree/main/client/src/pages/auth): React pages · Login, register, and email verification flows. · `client/src/pages/auth`
- [Dashboard pages](https://github.com/chaima-touj/stage-flow/tree/main/client/src/pages/dashboard): React pages · Authenticated workspace for profile, formations, requests, and student dashboard. · `client/src/pages/dashboard`
- [Workflows](https://github.com/chaima-touj/stage-flow/tree/main/client/src/pages): React pages · Applications, interviews, messages, notifications, settings, and AI assistant screens. · `client/src/pages`
- [Shell layout](https://github.com/chaima-touj/stage-flow/tree/main/client/src/components/layout): React layout · Persistent dashboard chrome including sidebar, topbar, and notification panel. · `client/src/components/layout`
- [Shared widgets](https://github.com/chaima-touj/stage-flow/tree/main/client/src/components/common): React components · Reusable UI such as uploads, course preview, section cards, and language flags. · `client/src/components/common`
- [Client state](https://github.com/chaima-touj/stage-flow/tree/main/client/src/context): React context · Auth, language, and theme global state boundaries. · `client/src/context`
- [i18n](https://github.com/chaima-touj/stage-flow/tree/main/client/src/i18n): localization · Locale initialization and translated content for en, fr, and ar. · `client/src/i18n`
- [API services](https://github.com/chaima-touj/stage-flow/tree/main/client/src/services): HTTP wrappers · Domain-specific frontend service layer for backend communication. · `client/src/services`

### Backend API

Express server with routes, controllers, models, middleware, and integration services.

- [Server entry](https://github.com/chaima-touj/stage-flow/blob/main/server/server.js): Express entry · Application bootstrap and runtime start point. · `server/server.js`
- [API routes](https://github.com/chaima-touj/stage-flow/tree/main/server/routes): Express routes · REST entry points for auth, formations, offers, applications, messaging, interviews, notifications, enrollment, favorites, and AI. · `server/routes`
- [Controllers](https://github.com/chaima-touj/stage-flow/tree/main/server/controllers): request handlers · Business request handling across core workflows and AI integration. · `server/controllers`
- [Middleware](https://github.com/chaima-touj/stage-flow/tree/main/server/middleware): request guards · Authentication, sanitization, upload handling, and centralized error processing. · `server/middleware`
- [Domain models](https://github.com/chaima-touj/stage-flow/tree/main/server/models): data models · Persistent entities for users, formations, offers, applications, enrollments, conversations, messages, interviews, notifications, and documents. · `server/models`
- [External services](https://github.com/chaima-touj/stage-flow/tree/main/server/services): integrations · Email delivery and Groq-powered AI integration. · `server/services`
- [Database](https://github.com/chaima-touj/stage-flow/blob/main/server/config/db.js): db config · Database connection boundary used by the backend runtime. · `server/config/db.js`
- [Formation content](https://github.com/chaima-touj/stage-flow/tree/main/server/formations): seed data · JSON-backed formation catalog content used for curated training data. · `server/formations`
- [Bootstrap scripts](https://github.com/chaima-touj/stage-flow/blob/main/server/seed.js): ops scripts · Seed and migration utilities for database initialization and evolution. · `server/seed.js`

## Connections

- App shell → Public pages: renders · App shell routes into public-facing pages.
- App shell → Auth pages: renders · App shell routes into authentication flows.
- App shell → Dashboard pages: renders · App shell routes into authenticated dashboard views.
- App shell → Workflows: renders · App shell exposes workflow-specific pages.
- App shell → Shell layout: uses · Dashboard pages are wrapped by shared layout chrome.
- Public pages → Shared widgets: shares UI · Public pages reuse common widgets and media helpers.
- Dashboard pages → Shared widgets: shares UI · Dashboard pages reuse common widgets.
- Workflows → Shared widgets: shares UI · Workflow pages reuse shared widgets and panels.
- Client state → App shell: provides state · Global auth, language, and theme state flow through the app.
- i18n → Client state: supports · Language context is backed by locale resources.
- API services → API routes: calls · Frontend service wrappers invoke backend API routes.
- Server entry → API routes: mounts · Server entry registers the API route set.
- API routes → Middleware: passes through · Routes apply auth, sanitize, upload, and error boundaries.
- API routes → Controllers: dispatches · Route handlers delegate to controllers.
- Controllers → Domain models: reads/writes · Controllers persist and query domain entities.
- Controllers → External services: uses · Controllers integrate email and AI services.
- Domain models → Database: persists via · Domain models depend on the database connection.
- Controllers → Formation content: loads · Formation controllers can draw from curated JSON catalog data.
- Bootstrap scripts → Database: initializes · Seed and migration scripts prepare database state.
- Middleware → External services: guards · Upload and auth boundaries protect service-facing operations.
