# unb-mds/2023-2-suagradeunb architecture

> Architecture diagram of the GitHub repository unb-mds/2023-2-suagradeunb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unb-mds/2023-2-suagradeunb
- Repository: https://github.com/unb-mds/2023-2-suagradeunb

## Overview

##### Project type and purpose
- This is a full-stack, containerized web application that helps University of Brasília students build and resolve conflicts in their class schedules.
- The backend is a Django REST API (with apps for core business logic, user management, and utilities), and the frontend is a Next.js/React single-page app.

##### File structure
- Top-level directories:
- `api/` – Django project, subdivided into three Django apps (`api`, `users`, `utils`) plus core settings and entrypoints.
- `web/` – Next.js app with React components, contexts, hooks, pages, API helper utilities, and styling.
- `docker/` & `docker-compose.yml` – container definitions for the two services (api, web) and the database.
- `docs/` – project documentation, including architecture and API docs.
- `scripts/` – helper scripts for configuration and testing.
- Key configuration/build files: `Makefile`, `docker-compose.yml`, `api/requirements.txt`, `web/package.json`, `mkdocs.yml`.
- Management commands in `api/api/management/commands` and `api/utils/management/commands` reveal custom tasks (e.g. `updatedb`, `initadmin`).

##### README for additional insights
- Technologies: Python 3.11, Django 4.2 + Django REST Framework, Node 20 + Next.js, Docker/Compose.
- External integrations: Google OAuth for authentication, SIGAA web scraping to populate course data.
- Architecture link points to a Figma whiteboard with high-level system design.

##### Elements
- Clear component labels (e.g., “Next.js Frontend”, “Django API”, “PostgreSQL”).
- Blue rectangles for services
- Green rounded rectangles for scheduled jobs or cron tasks

##### Detail without overthinking
- Break the Django API into sub-components if desired (e.g., Auth module, Schedule module, User module).
- Custom management commands and where they run.
- Ports (e.g., 8000, 3000) and environment variables if relevant to deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Docker Network"
        subgraph "Frontend Service" 
            FN["Next.js Frontend\n(port 3000)"]:::service
            subgraph "Client State Layer"
                FC1["UI Components"]:::service
                FC2["Contexts"]:::service
                FC3["Hooks"]:::service
            end
            FC4["API Utilities"]:::service
            CFG_FE["next.config.js\npackage.json\ntsconfig.json"]:::config
        end
        subgraph "Backend Service"
            BE["Django REST API\n(port 8000)"]:::service
            subgraph "Django Apps"
                CORE["Core Business Logic"]:::service
                USERS["User Management App"]:::service
                UTILS_APP["Utilities App"]:::service
            end
            subgraph "Entrypoints & Config"
                SETTINGS["core/settings"]:::config
                ENTRY["config/entrypoint.sh"]:::config
                MANAGE["manage.py"]:::config
            end
            subgraph "Management Commands"
                CMD1["updatedb.py"]:::cron
                CMD2["initadmin.py"]:::cron
                CMD3["updatemock.py"]:::cron
            end
            subgraph "Utilities & Integrations"
                SCRAP["web_scraping.py"]:::service
                JWT["SimpleJWT"]:::service
            end
            subgraph "Database Migrations"
                MIG1["api migrations"]:::config
                MIG2["users migrations"]:::config
            end
        end
        DB["PostgreSQL"]:::db
    end

    Browser["User Browser"]:::external
    SIGAA["SIGAA University Site"]:::cloud
    GOOGLE["Google OAuth"]:::cloud

    Browser -->|"HTTPS"| FN
    FN -->|"REST /api/*"| BE
    FN -->|"Auth Redirect"| GOOGLE
    GOOGLE -->|"OAuth Callback"| FN
    FN -->|"Token Exchange"| BE
    BE -->|"ORM Queries"| DB
    CMD1 -.->|"Scrape Courses"| SIGAA
    BE -->|"Validate Token"| GOOGLE

    click FN "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/web/app"
    click FC1 "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/web/app/components"
    click FC2 "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/web/app/contexts"
    click FC3 "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/web/app/hooks"
    click FC4 "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/web/app/utils/api"
    click CFG_FE "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/web/next.config.js"
    click CFG_FE "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/web/package.json"
    click CFG_FE "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/web/tsconfig.json"
    click BE "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/api/"
    click CORE "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/api/api"
    click USERS "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/api/users"
    click UTILS_APP "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/api/utils"
    click SETTINGS "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/api/core/settings"
    click ENTRY "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/api/config/entrypoint.sh"
    click MANAGE "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/api/manage.py"
    click CMD1 "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/api/api/management/commands/updatedb.py"
    click CMD2 "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/api/api/management/commands/initadmin.py"
    click CMD3 "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/api/utils/management/commands/updatemock.py"
    click SCRAP "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/api/utils/web_scraping.py"
    click JWT "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/api/users/simplejwt"
    click MIG1 "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/api/api/migrations"
    click MIG2 "https://github.com/unb-mds/2023-2-suagradeunb/tree/main/api/users/migrations"
    click DB "https://github.com/unb-mds/2023-2-suagradeunb/blob/main/docker-compose.yml"

    classDef service fill:#AED6F1,stroke:#1F618D,color:#1B2631;
    classDef db fill:#F9E79F,stroke:#B9770E,color:#1B2631;
    classDef cloud fill:#D6EAF8,stroke:#21618C,color:#1B2631;
    classDef cron fill:#ABEBC6,stroke:#196F3D,color:#1B2631;
    classDef config fill:#F5B7B1,stroke:#7B241C,color:#1B2631;
    classDef external fill:#D5DBDB,stroke:#566573,color:#1B2631;
```
