# oliad1/doro architecture

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

- Interactive diagram: https://gitdiagram.com/oliad1/doro
- Repository: https://github.com/oliad1/doro

## Overview

##### Project type and purpose
- This is a full-stack grade-tracking application (“Doro”) designed to scrape and aggregate grade components for 1700+ Waterloo courses and expose them through a web interface and API.
- The frontend is a Next.js/TypeScript web app with client-side state (Zustand) and schema validation (Zod).
- The backend is a Node.js service (running under bun/PM2) exposing REST endpoints, interacting with a Postgres database (Supabase), and AWS S3 for storage.
- A separate Python scraping service fetches course metadata and persists it to the database.

##### File structure
- Top level:
- frontend/ – Next.js app
- backend/ – Node.js API server
- docker-compose.yml – orchestrates containers
- frontend/src/app contains route handlers (Next.js App Router); src/APIClients wraps calls to backend endpoints; components/ houses UI.
- backend/server.ts boots the Express-style HTTP server, controllers/ define endpoints, services/ implement business logic, repositories/ handle data access, models/ define ORM schemas, middlewares/ handle auth.
- utils/s3/client.ts configures AWS S3.
- .env.sample files in both frontend and backend suggest separate environment configurations.
- README mentions deployment on AWS EC2 with NGINX reverse proxy, PM2 process manager.

##### README for additional insights
- Architecture summary: Frontend (Next.js, TypeScript, Zustand, Zod), Backend (Node.js on AWS EC2, Nginx, PM2), DB (Supabase/Postgres), Scraping (Python, BeautifulSoup, Pydantic).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["User Browser/Mobile"]:::ui
        NextJS["Next.js Frontend"]:::ui
        AppRouter["Route Handlers (App Router)"]:::ui
        APIClients["API Clients (REST wrappers)"]:::ui
        Stores["State Management (Zustand Stores)"]:::ui
        Providers["State Providers"]:::ui
        ZodSchemas["Schema Validation (Zod)"]:::ui
        UIComponents["UI Components"]:::ui

        Browser -->|HTTPS| NextJS
        NextJS -->|renders routes| AppRouter
        AppRouter -->|"calls"| APIClients
        APIClients -->|"manages state via"| Stores
        Stores --> Providers
        APIClients --> ZodSchemas
        NextJS --> UIComponents
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        APIGateway["NGINX/API Gateway"]:::backend
        NodeService["Node.js API Service"]:::backend
        Controllers["Controllers (Express Endpoints)"]:::backend
        Services["Business Logic Services"]:::backend
        Repos["Data Access Repositories"]:::backend
        Models["ORM Models/Schemas"]:::backend
        AuthMiddleware["Auth Middleware"]:::backend
        ErrorUtils["Error Handling Utilities"]:::backend
        Logger["Logging Utilities"]:::backend
        S3Client["AWS S3 Client"]:::backend

        APIGateway -->|forwards requests| NodeService
        NodeService --> Controllers
        Controllers --> Services
        Services --> Repos
        Repos --> Models
        Controllers --> AuthMiddleware
        NodeService --> ErrorUtils
        NodeService --> Logger
        NodeService --> S3Client
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Postgres["Managed Postgres (Supabase)"]:::infra
        S3Bucket["AWS S3 Bucket"]:::infra
        DockerComp["Docker Compose"]:::infra
    end

    %% Scraper Service
    subgraph "Scraper Service"
        direction TB
        Scraper["Python Scraper (BeautifulSoup/Pydantic)"]:::external
        Scraper -->|writes data| Postgres
        Scraper -->|uploads artifacts| S3Bucket
    end

    %% Deployment Infrastructure
    subgraph "Production Infrastructure"
        direction TB
        EC2["AWS EC2"]:::infra
        PM2["PM2 Process Manager"]:::infra
        EC2 --> PM2
        EC2 --> APIGateway
    end

    %% Connections between Backend and Infrastructure
    Repos -->|reads/writes| Postgres
    S3Client -->|file operations| S3Bucket

    %% Click Events - Frontend
    click NextJS "https://github.com/oliad1/doro/tree/main/frontend/"
    click AppRouter "https://github.com/oliad1/doro/tree/main/frontend/src/app/"
    click APIClients "https://github.com/oliad1/doro/tree/main/frontend/src/APIClients/"
    click Stores "https://github.com/oliad1/doro/tree/main/frontend/src/stores/"
    click Providers "https://github.com/oliad1/doro/tree/main/frontend/src/providers/"
    click ZodSchemas "https://github.com/oliad1/doro/blob/main/frontend/src/utils/schema/zodSchemas.ts"
    click UIComponents "https://github.com/oliad1/doro/tree/main/frontend/src/components/"
    click .env_frontend "https://github.com/oliad1/doro/blob/main/frontend/.env.sample"

    %% Click Events - Backend
    click NodeService "https://github.com/oliad1/doro/blob/main/backend/server.ts"
    click Controllers "https://github.com/oliad1/doro/tree/main/backend/controllers/"
    click Services "https://github.com/oliad1/doro/tree/main/backend/services/interfaces/"
    click Services "https://github.com/oliad1/doro/tree/main/backend/services/implementations/"
    click Repos "https://github.com/oliad1/doro/tree/main/backend/repositories/"
    click Models "https://github.com/oliad1/doro/blob/main/backend/models/index.ts"
    click AuthMiddleware "https://github.com/oliad1/doro/blob/main/backend/middlewares/auth.ts"
    click S3Client "https://github.com/oliad1/doro/blob/main/backend/utils/s3/client.ts"
    click ErrorUtils "https://github.com/oliad1/doro/blob/main/backend/utils/errorUtils.ts"
    click Logger "https://github.com/oliad1/doro/blob/main/backend/utils/logger.ts"
    click .env_backend "https://github.com/oliad1/doro/blob/main/backend/.env.sample"

    %% Click Events - Infrastructure
    click DockerComp "https://github.com/oliad1/doro/blob/main/docker-compose.yml"

    %% Styling
    classDef ui fill:#EEF6FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#E6F4EA,stroke:#257942,stroke-width:1px
    classDef infra fill:#FFF4E5,stroke:#D9822B,stroke-width:1px
    classDef external fill:#F2F2F2,stroke:#888888,stroke-width:1px
```
