# abdelqaouinabil/smirisapp architecture

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

- Interactive diagram: https://gitdiagram.com/abdelqaouinabil/smirisapp
- Repository: https://github.com/abdelqaouinabil/smirisapp

## Overview

##### Project Type & Purpose
- This is a monorepo full-stack web application (“SmirisApp”), a language-learning platform connecting students, tutors, and schools.
- Frontend: React/TypeScript SPA (Vite, Tailwind, i18n)
- Backend: Node.js/TypeScript API (Express-style routes, Passport JWT auth)
- Database: PostgreSQL

##### Main Components
a. User Clients
- Web browser (desktop, tablet, mobile)
- Roles: Student, Tutor, School, Admin
b. Frontend SPA
- Vite dev/production server
- Routes & pages (Homepage, Dashboards, Booking, Admin Panel, etc.)
- Contexts (AuthContext, ComparisonContext)
- UI component library (accordion, button, form, etc.)
- i18n subsystem (locale JSON files)
- PaymentIntegration & OAuth2Integration modules
c. Backend API Server
- Entry: server/src/server.ts
- Middleware: auth (JWT via Passport), errorHandler
- Routes (admin, auth, bookings, courses, payments, reviews, schools, tutors, visa)
- Database layer: connection.ts, migrations (init, add-subject-column), seed.ts, schema.sql
- File storage: server/uploads (CVs, certificates)
d. Database
- PostgreSQL instance
- Key tables: users, schools, tutors, courses, bookings, payments, visa_services
e. External Services
- Payment gateway (Stripe or similar)
- OAuth providers (Google, Facebook, etc.)
- (Optional) Email/SMS notifications, third-party visa API
f. Deployment & DevOps
- Dockerfiles (prod/dev), docker-compose.yml, deploy.sh
- CI/CD target (Vercel for frontend, container registry)

##### Relationships & Data Flows
- User → Frontend SPA (UI interactions, form submissions)
- SPA → Backend API (/api/*) over HTTP(S)
- Attaches JWT (access, refresh) for protected routes
- API → PostgreSQL via parameterized queries (connection.ts)
- API ↔ External services (payment gateway calls, OAuth token exchange, visa API if any)
- API → File Storage for upload/download of tutor files
- Backend emits notifications (pulled via API or websockets if implemented)

##### Architectural Patterns & Principles
- Monorepo separation: “src/” frontend vs. “server/src/” backend
- Layered backend:
- Config layer (passport.ts, connection.ts)
- Middleware layer (auth, error handling)
- Routing layer (per-entity route modules)
- Data access (migrations, seeds, raw SQL)
- SPA state management via React Context + custom hooks
- Internationalization via resource bundles (JSON locales)
- Component-driven UI library (atomic components under ui/)
- Secure RESTful API with role-based access control

##### Detailed Capture of Architectural Elements
- API authentication flow: login request, token issuance, token refresh, protected route check
- File upload/download path (HTTP multipart to /api/tutors/:id/files → uploads/)
- Major REST endpoints clusters (e.g., /api/bookings, /api/payments)
- Call out i18n lookup sequence if relevant (SPA → locales/*.json)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Clients
    subgraph "User Clients"
        Browser["Web Browser\n(Student, Tutor, School, Admin)"]:::client
    end

    %% Frontend SPA
    subgraph "Frontend SPA"
        Vite["Vite Build & Dev Server"]:::frontend
        Entry["SPA Entry Point\nmain.tsx / App.tsx"]:::frontend
        Pages["Pages\n(src/pages/)"]:::frontend
        Contexts["Contexts\nAuthContext & ComparisonContext"]:::frontend
        UI["UI Component Library\n(src/components/ui/)"]:::frontend
        PaymentFE["Payment Integration Module"]:::frontend
        OAuthFE["OAuth2 Integration Module"]:::frontend
        Protected["ProtectedRoute Component"]:::frontend
        I18n["Internationalization\n(src/i18n/)"]:::frontend
        APIClient["API Client Utility\nsrc/lib/api.ts"]:::frontend
    end

    %% Backend API Server
    subgraph "Backend API Server"
        Server["server.ts"]:::backend
        Config["Passport JWT Config"]:::backend
        Middleware["Middleware\nauth & errorHandler"]:::backend
        Routes["Route Modules\n(auth, admin, bookings, courses, payments, reviews, schools, tutors, visa)"]:::backend
        DBLayer["Database Layer\nconnection, migrations, schema, seed"]:::backend
        FileStorage["File Storage for Uploads"]:::storage
    end

    %% Database
    DB["PostgreSQL"]:::db

    %% External Services
    subgraph "External Services"
        PaymentGW["Payment Gateway"]:::external
        OAuthProvider["OAuth Providers"]:::external
        VisaAPI["Visa API"]:::external
    end

    %% DevOps
    subgraph "DevOps & Deployment"
        Docker["Docker & Compose Scripts"]:::devops
        CI["CI/CD (Vercel)"]:::devops
    end

    %% Connections
    Browser -->|UI interactions| Vite
    Vite -->|serves SPA| Entry
    Entry --> Pages
    Entry --> Contexts
    Entry --> UI
    Entry --> I18n
    Entry --> APIClient
    Entry --> Protected
    Entry --> PaymentFE
    Entry --> OAuthFE

    APIClient -->|HTTP + JWT| Server
    Server --> Config
    Server --> Middleware
    Server --> Routes
    Server --> DBLayer
    Server --> FileStorage
    Server -->|SQL Queries| DB
    Server -->|calls| PaymentGW
    Server -->|OAuth token exchange| OAuthProvider
    Server -->|visa requests| VisaAPI

    Docker --- Server
    Docker --- Vite
    Docker --- DB
    CI --- Vite

    %% Click Events
    click Vite "https://github.com/abdelqaouinabil/smirisapp/blob/main/vite.config.ts"
    click Vite "https://github.com/abdelqaouinabil/smirisapp/blob/main/package.json"
    click Entry "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/main.tsx"
    click Entry "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/App.tsx"
    click Pages "https://github.com/abdelqaouinabil/smirisapp/tree/main/src/pages/"
    click Contexts "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/contexts/AuthContext.tsx"
    click Contexts "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/contexts/ComparisonContext.tsx"
    click UI "https://github.com/abdelqaouinabil/smirisapp/tree/main/src/components/ui/"
    click PaymentFE "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/components/payment/PaymentIntegration.tsx"
    click OAuthFE "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/components/auth/OAuth2Integration.tsx"
    click Protected "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/components/ProtectedRoute.tsx"
    click I18n "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/i18n/index.ts"
    click I18n "https://github.com/abdelqaouinabil/smirisapp/tree/main/src/i18n/locales/"
    click APIClient "https://github.com/abdelqaouinabil/smirisapp/blob/main/src/lib/api.ts"
    click Server "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/server.ts"
    click Config "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/config/passport.ts"
    click DBLayer "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/database/connection.ts"
    click DBLayer "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/database/init.ts"
    click DBLayer "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/database/add-subject-column.ts"
    click DBLayer "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/database/schema.sql"
    click DBLayer "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/database/seed.ts"
    click Middleware "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/middleware/auth.ts"
    click Middleware "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/middleware/errorHandler.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/auth.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/admin.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/bookings.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/courses.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/payments.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/reviews.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/schools.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/tutors.ts"
    click Routes "https://github.com/abdelqaouinabil/smirisapp/blob/main/server/src/routes/visa.ts"
    click FileStorage "https://github.com/abdelqaouinabil/smirisapp/tree/main/server/uploads/"
    click Docker "https://github.com/abdelqaouinabil/smirisapp/tree/main/Dockerfile"
    click Docker "https://github.com/abdelqaouinabil/smirisapp/blob/main/Dockerfile.dev"
    click Docker "https://github.com/abdelqaouinabil/smirisapp/blob/main/docker-compose.yml"
    click Docker "https://github.com/abdelqaouinabil/smirisapp/blob/main/deploy.sh"
    click CI "https://github.com/abdelqaouinabil/smirisapp/blob/main/vercel.json"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000
    classDef frontend fill:#87CEFA,stroke:#000
    classDef backend fill:#90EE90,stroke:#000
    classDef db fill:#FFB347,stroke:#000
    classDef storage fill:#FFB347,stroke:#000
    classDef external fill:#DDA0DD,stroke:#000
    classDef devops fill:#F0E68C,stroke:#000
```
