# swebi/orderly architecture

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

- Interactive diagram: https://gitdiagram.com/swebi/orderly
- Repository: https://github.com/swebi/orderly

## Overview

##### Project Type and Purpose
Orderly is a full‑stack, user‑centric scheduling app. Its purpose is to let users log in with Google, save their class timetable, and then automatically scrape SRM Academia each midnight to push updated events into Google Calendar via background jobs.

##### Main Architectural Components
a. Frontend (Vercel‑hosted React app)
- Pages & Components (Login, Dashboard, TimetableForm, PrivateRoute, etc.)
- UI library (Shadcn / MagicUI) + routing + state/hooks (useAuthenticate, use-toast)
- HTTP client (axios wrapper) calling the backend API

b. Backend (AWS EC2–hosted Express server)
- REST API Layer
– Controllers: auth.controller (Google OAuth), api.controller (subject/timetable CRUD), admin.controller (manual trigger, job control)
– Middlewares: userVerification, adminVerification, errorHandler
– Routes: /auth, /api, /admin
- Job Queue & Workers
– BullMQ configuration (queue.js, procedure.js)
– Worker process (worker.js)
– BullBoard UI (bullBoard.js) for real‑time monitoring
- Web Scrapers (Puppeteer scripts in /scrapers)
– dayOrder.js, timetable.js, planner.js
- Business Logic & Helpers
– Google API utilities (googleUtils.js)
– Data transformation (generateEvent, timeConverter)
– Crypto, Prisma client for Postgres

c. Datastores & External Services
- PostgreSQL (via Prisma ORM) – persistent storage of users, subjects, timetables
- Redis – BullMQ’s backing store for job queues
- External HTTP services:
– SRM Academia website (Puppeteer scraping)
– Google OAuth & Calendar APIs

##### Relationships & Data Flows
1. User → Frontend: interactive UI in browser
2. Frontend → Backend (HTTP/JSON): login, CRUD operations, manual trigger
3. Backend → PostgreSQL (Prisma): read/write user data, timetables
4. Backend → Redis: enqueue scraping/calendar‑sync jobs
5. BullMQ Worker → Redis: fetch job, run scraper (Puppeteer) → generate events → call Google Calendar API
6. BullBoard ← Backend: serve dashboard on /admin/queues

##### Architectural Patterns & Principles
- Separation of Concerns:
– UI vs. API vs. background jobs
- Layered Architecture:
– Controllers → Services/Utils → Data Access
- Asynchronous Processing:
– BullMQ for reliable, retryable, scheduled tasks
- Modularization:
– /api, /scrapers, /bull, /utils each encapsulate distinct logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier (Browser)" 
        direction TB
        User["User"]:::external
        ReactApp["React App"]:::frontend
        PagesComps["Pages & Components"]:::frontend
        HooksUtils["Hooks & Utilities"]:::frontend
        User -->|"interacts with"| ReactApp
        ReactApp -->|"renders pages/components"| PagesComps
        ReactApp -->|"uses hooks/utils"| HooksUtils
    end

    %% Server Tier
    subgraph "Server Tier (AWS EC2)" 
        direction TB
        ExpressAPI["Express API"]:::backend
        Controllers["Controllers"]:::backend
        Middlewares["Middlewares"]:::backend
        Routes["Routes"]:::backend
        BullService["BullMQ Queue & Worker"]:::queue
        Scrapers["Web Scrapers"]:::backend
        Utils["Business Logic & Helpers"]:::backend
        ORM["Prisma ORM"]:::backend

        ReactApp -->|"HTTP/JSON"| ExpressAPI
        ExpressAPI --> Controllers
        ExpressAPI --> Middlewares
        ExpressAPI --> Routes
        ExpressAPI --> ORM
        Controllers --> Utils
        ExpressAPI --> BullService
        BullService --> Scrapers
        Scrapers --> Utils
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        Postgres["Postgres (Prisma)"]:::db
        Redis["Redis"]:::db
        ORM --> Postgres
        BullService --> Redis
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SRM["SRM Academia"]:::external
        Google["Google OAuth & Calendar API"]:::external
        Scrapers -->|"Puppeteer scrape"| SRM
        Utils -->|"calls Calendar API"| Google
    end

    %% Click Events - Client
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/src/App.jsx"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/src/main.jsx"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/src/index.css"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/index.html"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/pages/Dashboard.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/pages/Layout.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/pages/Privacy.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/pages/Terms.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/PrivateRoute.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/TimetableForm.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/Timetable.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/EventBlock.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/SubjectInput.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/ScraperModal.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/Spinner.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/Navbar.jsx"
    click PagesComps "https://github.com/swebi/orderly/blob/main/client/src/components/Footer.jsx"
    click HooksUtils "https://github.com/swebi/orderly/blob/main/client/src/hooks/useAuthenticate.js"
    click HooksUtils "https://github.com/swebi/orderly/blob/main/client/src/hooks/use-toast.js"
    click HooksUtils "https://github.com/swebi/orderly/blob/main/client/src/lib/auth.js"
    click HooksUtils "https://github.com/swebi/orderly/blob/main/client/src/lib/axios.js"
    click HooksUtils "https://github.com/swebi/orderly/blob/main/client/src/lib/utils.js"

    %% Click Events - Server
    click ExpressAPI "https://github.com/swebi/orderly/blob/main/server/src/index.js"
    click Controllers "https://github.com/swebi/orderly/blob/main/server/src/api/controllers/auth.controller.js"
    click Controllers "https://github.com/swebi/orderly/blob/main/server/src/api/controllers/api.controller.js"
    click Controllers "https://github.com/swebi/orderly/blob/main/server/src/api/controllers/admin.controller.js"
    click Middlewares "https://github.com/swebi/orderly/blob/main/server/src/api/middlewares/userVerification.js"
    click Middlewares "https://github.com/swebi/orderly/blob/main/server/src/api/middlewares/adminVerification.js"
    click Middlewares "https://github.com/swebi/orderly/blob/main/server/src/api/middlewares/errorHandler.js"
    click Routes "https://github.com/swebi/orderly/blob/main/server/src/api/routes/auth.router.js"
    click Routes "https://github.com/swebi/orderly/blob/main/server/src/api/routes/api.router.js"
    click Routes "https://github.com/swebi/orderly/blob/main/server/src/api/routes/admin.router.js"
    click BullService "https://github.com/swebi/orderly/blob/main/server/src/bull/queue.js"
    click BullService "https://github.com/swebi/orderly/blob/main/server/src/bull/procedure.js"
    click BullService "https://github.com/swebi/orderly/blob/main/server/src/bull/worker.js"
    click BullService "https://github.com/swebi/orderly/blob/main/server/src/bull/bullBoard.js"
    click Scrapers "https://github.com/swebi/orderly/blob/main/server/src/scrapers/dayOrder.js"
    click Scrapers "https://github.com/swebi/orderly/blob/main/server/src/scrapers/timetable.js"
    click Scrapers "https://github.com/swebi/orderly/blob/main/server/src/scrapers/planner.js"
    click Utils "https://github.com/swebi/orderly/blob/main/server/src/utils/googleUtils.js"
    click Utils "https://github.com/swebi/orderly/blob/main/server/src/utils/generateEvent.js"
    click Utils "https://github.com/swebi/orderly/blob/main/server/src/utils/generateTimetable.js"
    click Utils "https://github.com/swebi/orderly/blob/main/server/src/utils/timeConverter.js"
    click Utils "https://github.com/swebi/orderly/blob/main/server/src/utils/crypto.js"
    click Utils "https://github.com/swebi/orderly/blob/main/server/src/utils/data.js"
    click ORM "https://github.com/swebi/orderly/blob/main/server/prisma/schema.prisma"
    click ORM "https://github.com/swebi/orderly/blob/main/server/prisma/prisma.client.js"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/vercel.json"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/vite.config.js"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/postcss.config.mjs"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/eslint.config.js"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/jsconfig.json"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/jsconfig.app.json"
    click ReactApp "https://github.com/swebi/orderly/blob/main/client/.gitignore"
    click ExpressAPI "https://github.com/swebi/orderly/blob/main/server/.gitignore"
    click ReactApp "https://github.com/swebi/orderly/blob/main/README.md"

    %% Styles
    classDef frontend fill:#a2d2ff,stroke:#000,stroke-width:1px
    classDef backend fill:#caffbf,stroke:#000,stroke-width:1px
    classDef db fill:#bde0fe,stroke:#000,stroke-width:1px
    classDef external fill:#ffafcc,stroke:#000,stroke-width:1px
    classDef queue fill:#ffd6a5,stroke:#000,stroke-width:1px
```
