# nicholas-sliter/middcourses2 architecture

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

- Interactive diagram: https://gitdiagram.com/nicholas-sliter/middcourses2
- Repository: https://github.com/nicholas-sliter/middcourses2

## Overview

##### Main System Components

a. Client Layer:
- Next.js Frontend (SSR)
- React Components
- User Interface Elements (Reviews, Course Discovery, Rankings)

b. API Layer:
- REST API endpoints (/api/*)
- Authentication Services
- Data Processing Services

c. Database Layer:
- PostgreSQL Database
- Knex.js ORM
- Data Models (Courses, Reviews, Users, etc.)

d. External Services:
- Google OAuth
- Middlebury Course Catalog Integration
- Middlebury Directory Integration

##### Key Relationships to Highlight

- Client-to-API interactions
- API-to-Database flows
- Authentication flows
- Data pipeline processes
- External service integrations

##### Detailed Component Breakdown

Frontend Components (Blue):
- Course Discovery Interface
- Review Management System
- User Profile Management
- Search & Rankings Interface
- Schedule Planning Tools

API Services (Green):
- Course Management API
- Review Processing API
- User Management API
- Search & Rankings API
- Authentication API

Database Components (Yellow):
- Course Data Store
- User Profiles
- Reviews & Ratings
- Department Information
- Instructor Data

External Services (Purple):
- Google OAuth Provider
- Middlebury Course Catalog
- Middlebury Directory
- Analytics Services

##### Special Features to Highlight

Create subsystems for:
- Review Quality Control System
- Course Ranking Algorithm
- Recommendation Engine
- Data Pipeline Automation
- Permission Management

##### Data Flow Patterns

Flows:
**User -> Authentication -> Review Submission -> Quality Control -> Database**
**Course Search -> Ranking Algorithm -> Recommendation Engine -> User Interface**
**External Data -> Data Pipeline -> Database -> API -> Frontend**

##### Security Boundaries

Clearly mark:
- Authentication boundaries
- Admin access zones
- Public vs. authenticated content
- Data validation checkpoints

##### Deployment Architecture

Include:
- Heroku hosting
- PostgreSQL database
- Next.js SSR setup
- External service connections

This system design should reflect the modern web application architecture while highlighting the unique features of MiddCourses 2.0, such as its review quality control, course ranking system, and integration with Middlebury College's systems.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef frontend fill:#3498db,color:white
    classDef api fill:#2ecc71,color:white
    classDef database fill:#f1c40f,color:black
    classDef external fill:#9b59b6,color:white
    classDef security fill:#e74c3c,color:white

    %% Client Layer
    subgraph ClientLayer
        FE[Next.js Frontend]:::frontend
        RC[React Components]:::frontend
        UI[User Interface]:::frontend
        
        FE --> RC
        RC --> UI
    end
    click FE "https://github.com/Nicholas-Sliter/middcourses2/tree/main/src/pages"
    click RC "https://github.com/Nicholas-Sliter/middcourses2/tree/main/src/components"
    click UI "https://github.com/Nicholas-Sliter/middcourses2/tree/main/src/components/common"

    %% API Layer
    subgraph APILayer
        API[REST API Endpoints]:::api
        AUTH[Authentication Services]:::security
        DPS[Data Processing Services]:::api
        
        API --> AUTH
        API --> DPS
    end
    click API "https://github.com/Nicholas-Sliter/middcourses2/tree/main/src/pages/api"
    click AUTH "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/pages/api/auth/[...nextauth].ts"
    click DPS "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/lib/backend/database-utils.ts"

    %% Database Layer
    subgraph DatabaseLayer
        DB[(PostgreSQL)]:::database
        ORM[Knex.js ORM]:::database
        DM[Data Models]:::database
        
        ORM --> DB
        DM --> ORM
    end
    click DB "https://github.com/Nicholas-Sliter/middcourses2/tree/main/src/lib/backend/database"
    click DM "https://github.com/Nicholas-Sliter/middcourses2/tree/main/data"

    %% External Services
    subgraph ExternalServices
        GAUTH[Google OAuth]:::external
        MCC[Middlebury Course Catalog]:::external
        MD[Middlebury Directory]:::external
    end

    %% Feature Components
    subgraph Features
        RVS[Review System]:::frontend
        CMS[Course Management]:::frontend
        SPS[Schedule Planning]:::frontend
        SRC[Search & Rankings]:::frontend
    end
    click RVS "https://github.com/Nicholas-Sliter/middcourses2/tree/main/src/components/Review"
    click CMS "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/components/CourseCard.tsx"
    click SPS "https://github.com/Nicholas-Sliter/middcourses2/tree/main/src/components/Schedule"
    click SRC "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/components/common/SearchBox.tsx"

    %% Core Services
    subgraph CoreServices
        SS[Search Service]:::api
        REC[Recommendations]:::api
        DP[Data Pipeline]:::api
        QC[Quality Control]:::api
    end
    click SS "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/lib/backend/database/rankings.ts"
    click REC "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/lib/backend/recommendations.ts"
    click DP "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/lib/backend/pipeline.ts"

    %% Background Jobs
    subgraph Jobs
        PC[Permission Checks]:::api
        DS[Department Stats]:::api
    end
    click PC "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/jobs/checkPermissions.js"
    click DS "https://github.com/Nicholas-Sliter/middcourses2/blob/main/src/jobs/getDepartmentReviewCounts.js"

    %% Relationships
    ClientLayer --> APILayer
    APILayer --> DatabaseLayer
    APILayer --> ExternalServices
    Features --> APILayer
    CoreServices --> DatabaseLayer
    Jobs --> DatabaseLayer
    ExternalServices --> APILayer

    %% Legend
    subgraph Legend
        L1[Frontend]:::frontend
        L2[API]:::api
        L3[Database]:::database
        L4[External]:::external
        L5[Security]:::security
    end
```
