# med10s/ensaf-academia architecture

> Architecture diagram of the GitHub repository med10s/ensaf-academia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/med10s/ensaf-academia
- Repository: https://github.com/med10s/ensaf-academia

## Overview

##### Project type and purpose
- This is a full-stack academic platform built with Next.js 13 (app-directory), TypeScript, Tailwind CSS, Drizzle ORM, and Supabase.
- It provides student and professor portals, an admin console (with academies, courses, user management, statistics, email-logs), and authentication flows (login, register, password reset, email verification).

##### File structure
- “app/” holds Next.js server- and client-side pages and layouts: public pages (/, /about, /courses, /dashboard, /profile), auth (/auth/*), and an admin namespace (/admin/*).
- “components/” contains reusable UI and layout primitives, organized by domain (Header, dashboard cards, admin tables, auth forms, providers, ui/*).
- “services/” implements business logic and data access via action functions (academy-actions, auth-actions, email-actions, etc.), split into server-only and shared.
- “lib/” and “utils/” provide low-level wrappers: Supabase clients (admin and server), Drizzle database schema and migrations, email-service, i18n, helpers.
- Config and orchestration files: middleware.ts (route-level auth guard), next.config.mjs, drizzle.config.ts, supabase/init.sql, scripts/test-db-connection.js, Tailwind and PostCSS configs.

##### README
- Confirms the platform’s academic scope for ENSAF students and professors.
- Mentions .env.local configuration for Supabase credentials, SMTP/email provider, and any third-party API keys.

a. Main components:
- Client (Browser): React client components, navigation, forms.
- Next.js Application Server:
- Server Components (data fetching via services)
- Client Components (UI hydration)
- Middleware (route guards, auth checks)
- API Routes or Server Actions (when invoked from the UI)
- Service Layer: services/actions/* modules containing domain logic.
- Data Layer:
- Supabase Auth & Database (PostgreSQL) accessed via Supabase SDK
- Drizzle ORM for migrations and type-safe queries
- External Services:
- Email Service (SMTP or SendGrid, wrapped in lib/email/email-service.ts)
- (Potential) Storage if using Supabase Storage for images
b. Relationships and interactions:
- Browser ↔ Next.js Server: HTTP(S) requests (page loads, form submissions, client RPC calls).
- Next.js Server → Middleware → Services: incoming requests pass through middleware for auth/session, then reach server or client components that call service functions.
- Services → Supabase SDK or Drizzle → PostgreSQL: business logic functions perform queries, mutations, and migrations.
- Services → Email Service: to send verification, password reset, notifications.
c. Architectural patterns / design principles:
- Layered architecture (Presentation → Business Logic → Data Access).
- Domain-driven modules in “services/actions”.
- Server/Client component separation offered by Next.js 13.
- Centralized state and queries via React-Query provider (components/providers/react-query-provider.tsx).
- Authentication via Supabase middleware and AuthProvider.
d. Relevant technologies:
- Next.js 13 (app dir, server components)
- React + TypeScript
- Drizzle ORM + raw SQL migrations
- Supabase SDK for Auth & Database
- Tailwind CSS + PostCSS
- React-Query, Sonner (toasts), ReCaptcha
- Node.js email library (in lib/email)

##### Final advice
- Be as granular as practical: group related pages under “App Pages” but call out the /admin and /auth sub-domains.
- How services map to database tables and external providers.
- Flow of authentication/session context via middleware and providers.
- Don’t omit the Drizzle/SQL migration pipeline—even if it only runs at build/deploy time, it’s a core part of the data-schema lifecycle.
- Use consistent iconography and labeling so any new engineer can trace a user’s request from the browser all the way to the database and back.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        Browser["Browser"]:::client
    end

    %% Next.js Server Layer
    subgraph "Next.js Server"
        Middleware["Middleware<br/>(middleware.ts)"]:::backend
        subgraph "App Pages" 
            RootLayout["app/layout.tsx"]:::frontend
            HomePage["app/page.tsx"]:::frontend
            AboutPage["app/about/page.tsx"]:::frontend
            CoursePage["app/courses/[id]/page.tsx"]:::frontend
            DashboardPage["app/dashboard/page.tsx"]:::frontend
            ProfilePage["app/profile/page.tsx"]:::frontend
        end
        subgraph "Auth Pages" 
            AuthLogin["app/auth/login/page.tsx"]:::frontend
            AuthRegister["app/auth/register/page.tsx"]:::frontend
            AuthForgot["app/auth/forgot-password/page.tsx"]:::frontend
            AuthReset["app/auth/reset-password/page.tsx"]:::frontend
            AuthVerify["app/auth/verify-email/page.tsx"]:::frontend
            AuthError["app/auth/error/page.tsx"]:::frontend
        end
        subgraph "Admin Pages" 
            AdminDashboard["app/admin/dashboard/page.tsx"]:::frontend
            AdminLoading["app/admin/dashboard/loading.tsx"]:::frontend
            AdminAcademiesList["app/admin/academies/list/page.tsx"]:::frontend
            AdminAcademyNew["app/admin/academies/new/page.tsx"]:::frontend
            AdminAcademyDetail["app/admin/academies/[id]/page.tsx"]:::frontend
            AdminAcademyEdit["app/admin/academies/[id]/edit/page.tsx"]:::frontend
            AdminCourseEdit["app/admin/courses/[id]/edit/page.tsx"]:::frontend
            AdminUsersList["app/admin/users/list/page.tsx"]:::frontend
            AdminUserDetail["app/admin/users/[id]/page.tsx"]:::frontend
            AdminUsersLoading["app/admin/users/loading.tsx"]:::frontend
            AdminStatistics["app/admin/statistics/page.tsx"]:::frontend
            AdminStatsLoading["app/admin/statistics/loading.tsx"]:::frontend
            AdminEmailLogs["app/admin/email-logs/page.tsx"]:::frontend
            AdminAccessRequests["app/admin/access-requests/page.tsx"]:::frontend
            AdminARLoading["app/admin/access-requests/loading.tsx"]:::frontend
            AdminProfessors["app/admin/professors/page.tsx"]:::frontend
            AdminCahier["app/admin/cahierCarge/page.tsx"]:::frontend
        end
        Middleware -->|"guards/auth"| RootLayout
        Middleware -->|"guards/auth"| AuthLogin
        Middleware -->|"guards/admin"| AdminDashboard
    end

    %% Service Layer
    subgraph "Service Layer"
        AcademyActions["academy-actions.ts"]:::service
        AuthActions["auth-actions.ts"]:::service
        AdminActions["admin-actions.ts"]:::service
        DashboardActions["dashboard-actions.ts"]:::service
        UserActions["user-actions.ts"]:::service
        ProfileActions["profile-actions.ts"]:::service
        EmailActions["email-actions.ts"]:::service
        ImageActions["image-actions.ts"]:::service
        DBActions["db-actions.ts"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        SupabaseAuth["Supabase Auth"]:::data
        PostgreSQL["PostgreSQL"]:::data
        DrizzleSchema["Drizzle Schema & Migrations"]:::data
    end

    %% External Services
    subgraph "External Services"
        EmailService["Email Service"]:::external
    end

    %% Flows
    Browser -->|"page load / form submit"| Middleware
    RootLayout -->|"renders"| AcademyActions
    AuthLogin -->|"calls authActions.login()"| AuthActions
    AdminDashboard -->|"calls adminActions.*"| AdminActions
    AcademyActions -->|"query/mutate"| SupabaseAuth
    AcademyActions -->|"query/mutate"| PostgreSQL
    AuthActions -->|"session via"| SupabaseAuth
    DashboardActions -->|"select stats"| PostgreSQL
    UserActions -->|"CRUD users"| PostgreSQL
    ProfileActions -->|"update profile"| PostgreSQL
    EmailActions -->|"sendEmail()"| EmailService
    ImageActions -->|"upload to"| SupabaseAuth
    DBActions -->|"run migrations"| DrizzleSchema

    %% Click events
    click RootLayout "https://github.com/med10s/ensaf-academia/blob/main/app/layout.tsx"
    click HomePage "https://github.com/med10s/ensaf-academia/blob/main/app/page.tsx"
    click AboutPage "https://github.com/med10s/ensaf-academia/blob/main/app/about/page.tsx"
    click CoursePage "https://github.com/med10s/ensaf-academia/blob/main/app/courses/[id]/page.tsx"
    click DashboardPage "https://github.com/med10s/ensaf-academia/blob/main/app/dashboard/page.tsx"
    click ProfilePage "https://github.com/med10s/ensaf-academia/blob/main/app/profile/page.tsx"
    click AuthLogin "https://github.com/med10s/ensaf-academia/blob/main/app/auth/login/page.tsx"
    click AuthRegister "https://github.com/med10s/ensaf-academia/blob/main/app/auth/register/page.tsx"
    click AuthForgot "https://github.com/med10s/ensaf-academia/blob/main/app/auth/forgot-password/page.tsx"
    click AuthReset "https://github.com/med10s/ensaf-academia/blob/main/app/auth/reset-password/page.tsx"
    click AuthVerify "https://github.com/med10s/ensaf-academia/blob/main/app/auth/verify-email/page.tsx"
    click AuthError "https://github.com/med10s/ensaf-academia/blob/main/app/auth/error/page.tsx"
    click AdminDashboard "https://github.com/med10s/ensaf-academia/blob/main/app/admin/dashboard/page.tsx"
    click AdminLoading "https://github.com/med10s/ensaf-academia/blob/main/app/admin/dashboard/loading.tsx"
    click AdminAcademiesList "https://github.com/med10s/ensaf-academia/blob/main/app/admin/academies/list/page.tsx"
    click AdminAcademyNew "https://github.com/med10s/ensaf-academia/blob/main/app/admin/academies/new/page.tsx"
    click AdminAcademyDetail "https://github.com/med10s/ensaf-academia/blob/main/app/admin/academies/[id]/page.tsx"
    click AdminAcademyEdit "https://github.com/med10s/ensaf-academia/blob/main/app/admin/academies/[id]/edit/page.tsx"
    click AdminCourseEdit "https://github.com/med10s/ensaf-academia/blob/main/app/admin/courses/[id]/edit/page.tsx"
    click AdminUsersList "https://github.com/med10s/ensaf-academia/blob/main/app/admin/users/list/page.tsx"
    click AdminUserDetail "https://github.com/med10s/ensaf-academia/blob/main/app/admin/users/[id]/page.tsx"
    click AdminUsersLoading "https://github.com/med10s/ensaf-academia/blob/main/app/admin/users/loading.tsx"
    click AdminStatistics "https://github.com/med10s/ensaf-academia/blob/main/app/admin/statistics/page.tsx"
    click AdminStatsLoading "https://github.com/med10s/ensaf-academia/blob/main/app/admin/statistics/loading.tsx"
    click AdminEmailLogs "https://github.com/med10s/ensaf-academia/blob/main/app/admin/email-logs/page.tsx"
    click AdminAccessRequests "https://github.com/med10s/ensaf-academia/blob/main/app/admin/access-requests/page.tsx"
    click AdminARLoading "https://github.com/med10s/ensaf-academia/blob/main/app/admin/access-requests/loading.tsx"
    click AdminProfessors "https://github.com/med10s/ensaf-academia/blob/main/app/admin/professors/page.tsx"
    click AdminCahier "https://github.com/med10s/ensaf-academia/blob/main/app/admin/cahierCarge/page.tsx"
    click AcademyActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/academy-actions.ts"
    click AuthActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/auth-actions.ts"
    click AdminActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/admin-actions.ts"
    click DashboardActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/dashboard-actions.ts"
    click UserActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/user-actions.ts"
    click ProfileActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/profile-actions.ts"
    click EmailActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/email-actions.ts"
    click ImageActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/image-actions.ts"
    click DBActions "https://github.com/med10s/ensaf-academia/blob/main/services/actions/db-actions.ts"
    click DrizzleSchema "https://github.com/med10s/ensaf-academia/blob/main/lib/db/schema.ts"
    click EmailService "https://github.com/med10s/ensaf-academia/blob/main/lib/email/email-service.ts"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085
    classDef frontend fill:#b8daff,stroke:#004085,color:#004085
    classDef backend fill:#d6d8db,stroke:#6c757d,color:#6c757d
    classDef service fill:#d4edda,stroke:#155724,color:#155724
    classDef data fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
