# pennlabs/office-hours-queue architecture

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

- Interactive diagram: https://gitdiagram.com/pennlabs/office-hours-queue
- Repository: https://github.com/pennlabs/office-hours-queue

## Overview

##### Main Components
- Frontend Application:
- Built with Next.js/React.
- Contains pages, components, hooks, contexts, utilities, and styling files.
- Runs in its own container (Dockerfile is present) and listens on port 3000 (default from the README).
- Backend Application:
- Developed using Django.
- Located under the “backend” folder (manage.py, settings, URLs, WSGI/ASGI setups).
- Implements RESTful API endpoints (documentation accessible at /api/documentation) for the frontend.
- Integrates Celery (for asynchronous tasks) and possibly channels for real-time features (presence of asgi.py and routing files).
- Has a PostgreSQL database as its main persistence store (instructions on migrating and creating superusers, plus hints for PostgreSQL installation).
- Configured with multiple environment-specific settings (development, production, staging, etc.).
- Uses Nginx as a reverse proxy (nginx-proddev.conf is present) for production-like configurations.
- Database:
- Although not explicitly visible as a folder, the setup instructions refer to using PostgreSQL.
- Likely containerized (managed by docker-compose in the backend’s docker-compose.yaml), and the README mentions a persistent “/backend/postgres” storage directory.
- Containerization & Orchestration:
- Docker is used for both the backend and frontend; each has its own Dockerfile.
- Docker Compose is used to bring up the services (and there’s a specific “proddev” profile for production emulation).
- Kubernetes configurations (found in the “k8s” directory) further describe production deployment.

##### Relationships and Data Flows
- Browser/Client:
- Initiates requests to the frontend application (Next.js) using HTTP.
- The frontend communicates with the backend API endpoints.
- Frontend Application:
- Serves static pages and handles client-side interactions.
- Makes HTTP requests (likely RESTful calls) to the backend.
- Backend Application:
- Receives API requests from the frontend.
- Interacts with the PostgreSQL database for CRUD operations.
- Uses Celery workers for background tasks (e.g., handling asynchronous operations or email sending, as suggested by email templates in the templates folder).
- Might be managed behind an Nginx proxy in production.
- Database:
- Stores application data (e.g., user information, course data, queue entries).
- Deployment Pipeline:
- The project includes GitHub workflows (.github/workflows) for CI/CD.
- Kubernetes manifests in the “k8s” folder are used for deploying and managing the application containers in a cluster.

##### Architectural Patterns and Technologies
- Separation of Concerns:
- Clear delineation between frontend and backend responsibilities.
- Containerization:
- Both frontend and backend are containerized allowing for consistent deployment.
- Environment Configurations:
- Multiple configuration settings for various environments (development, staging, production) in the backend settings.
- Asynchronous Processing:
- Celery is utilized for tasks that are done asynchronously.
- Modern Frontend Technologies:
- Using Next.js/React implies use of modern single-page application (SPA) principles and server-side rendering (SSR) where applicable.
- Deployment Orchestration:
- Docker Compose for local development and Kubernetes for production orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser/Client"]:::browser

    subgraph "Frontend Layer"
        FrontendApp["Frontend App (Next.js/React, Dockerized, Port 3000)"]:::frontend
    end

    subgraph "Backend Layer"
        NginxProxy["Nginx Reverse Proxy (Production)"]:::proxy
        BackendApp["Backend App (Django, REST API)"]:::backend
        CeleryWorker["Celery Worker (Async Tasks)"]:::celery
        Database["PostgreSQL Database (Containerized)"]:::database
    end

    subgraph "Deployment & Orchestration"
        CI["CI/CD Pipeline (GitHub Actions)"]:::ci
        DockerFrontend["Frontend Dockerfile"]:::container
        DockerBackend["Backend Dockerfile"]:::container
        K8s["Kubernetes Deployment"]:::k8s
    end

    %% Data Flow Connections
    Browser -->|"HTTPRequest"| FrontendApp
    Browser -->|"HTTPRequest"| NginxProxy
    NginxProxy -->|"ProxiesTo"| BackendApp
    FrontendApp -->|"APICall"| BackendApp
    BackendApp -->|"CRUDQuery"| Database
    BackendApp -->|"AsyncTask"| CeleryWorker

    %% Deployment Flow Connections
    CI -->|"Builds"| DockerFrontend
    CI -->|"Builds"| DockerBackend
    DockerFrontend -->|"DeploysAs"| FrontendApp
    DockerBackend -->|"DeploysAs"| BackendApp
    CI -->|"DeploysTo"| K8s

    %% Click Events
    click FrontendApp "https://github.com/pennlabs/office-hours-queue/tree/master/frontend/"
    click BackendApp "https://github.com/pennlabs/office-hours-queue/tree/master/backend/"
    click CeleryWorker "https://github.com/pennlabs/office-hours-queue/blob/master/backend/officehoursqueue/celery.py"
    click NginxProxy "https://github.com/pennlabs/office-hours-queue/blob/master/backend/nginx-proddev.conf"
    click Database "https://github.com/pennlabs/office-hours-queue/blob/master/backend/docker-compose.yaml"
    click DockerFrontend "https://github.com/pennlabs/office-hours-queue/tree/master/frontend/Dockerfile"
    click DockerBackend "https://github.com/pennlabs/office-hours-queue/tree/master/backend/Dockerfile"
    click CI "https://github.com/pennlabs/office-hours-queue/blob/master/.github/workflows/shared-build-deploy.yaml"
    click K8s "https://github.com/pennlabs/office-hours-queue/tree/master/k8s/"

    %% Styles
    classDef browser fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef frontend fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef backend fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef celery fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef proxy fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef database fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef ci fill:#00CED1,stroke:#000,stroke-width:2px;
    classDef k8s fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef container fill:#FFC0CB,stroke:#000,stroke-width:2px;
```
