How chaima-touj/stage-flow works
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: main.jsx App shell · controllers Controllers · routes API routes · common Shared widgets
Components 19
Frontend SPA
React/Vite client with public pages, dashboard shell, global state, and API wrappers.
- App shell · Vite bootstrapping and top-level app composition.
client/src/main.jsx - Public pages · Landing, formations, offers, and public offer detail views.
client/src/pages - Auth pages · Login, register, and email verification flows.
client/src/pages/auth - Dashboard pages · Authenticated workspace for profile, formations, requests, and student dashboard.
client/src/pages/dashboard - Workflows · Applications, interviews, messages, notifications, settings, and AI assistant screens.
client/src/pages - Shell layout · Persistent dashboard chrome including sidebar, topbar, and notification panel.
client/src/components/layout - Shared widgets · Reusable UI such as uploads, course preview, section cards, and language flags.
client/src/components/common - Client state · Auth, language, and theme global state boundaries.
client/src/context - i18n · Locale initialization and translated content for en, fr, and ar.
client/src/i18n - API services · 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 · Application bootstrap and runtime start point.
server/server.js - API routes · REST entry points for auth, formations, offers, applications, messaging, interviews, notifications, enrollment, favorites, and AI.
server/routes - Controllers · Business request handling across core workflows and AI integration.
server/controllers - Middleware · Authentication, sanitization, upload handling, and centralized error processing.
server/middleware - Domain models · Persistent entities for users, formations, offers, applications, enrollments, conversations, messages, interviews, notifications, and documents.
server/models - External services · Email delivery and Groq-powered AI integration.
server/services - Database · Database connection boundary used by the backend runtime.
server/config/db.js - Formation content · JSON-backed formation catalog content used for curated training data.
server/formations - Bootstrap scripts · Seed and migration utilities for database initialization and evolution.
server/seed.js
Connections 20
- 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.