# kandeel4411/peam-backend architecture

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

- Interactive diagram: https://gitdiagram.com/kandeel4411/peam-backend
- Repository: https://github.com/kandeel4411/peam-backend

## Overview

##### Main Components
- Docker & Environment Management:
- A Docker container (or multiple containers) providing the runtime for the Django server.
- This includes different Docker configurations (docker-compose.dev.yml, docker-compose.prod.yml, docker-compose.ci.yml) and environment files (.env files for local development and production).
- Django Backend Server:
- The central backend service organized under the “src” directory.
- It contains the Django project’s “core” module (settings, asgi.py, wsgi.py, admin, management commands, etc.).
- Django Apps:
- Database and Data Flow:
- External Dependencies:
- Integration with external services such as tree-sitter repositories that need to be cloned and compiled for plagiarism detection.
- Dependencies managed by Poetry (or pip) and possibly any external API calls if applicable.

##### Relationships and Interactions
- That incoming web requests (displayed as HTTP requests directed for API documentation at http://localhost:8000/) hit the Django server running within a Docker container.
- That the Django server routes requests to the respective apps (authentication for login/session management, courses for course-related content, plagiarism for detecting similarities, etc.).
- Database as a central component that all apps connect to for CRUD operations.
- For the plagiarism module, show an internal relationship that interacts with vendor components (the tree-sitter language parsers) to perform its analysis.
- Management commands and background jobs (e.g., setup commands) can be shown as auxiliary components interacting with the main system.

##### Highlighting Architectural Patterns & Design Principles
- Modular MVC-like architecture of Django, clearly separated into apps.
- Configuration management through environment variables and separate settings files (base, dev, prod, test).
- The use of Docker for containerized deployments, ensuring environment consistency.
- An emphasis on code quality (with linting, testing, a Makefile for common tasks, and CI through GitHub Workflows).

##### Relevant Technologies & Frameworks
- Django (version 3.1.4 as per the badge) as the main web framework.
- Python 3.8+.
- Docker for container orchestration.
- Poetry for dependency management.
- GitHub Actions for CI (as seen from the workflows).
- PostgreSQL (implied from “postgres” env files) as the backend database.
- External tree-sitter repositories for programming language parsing within plagiarism detection.

##### Overall Detail
- Be very detailed: capture each logical layer from container orchestration (Docker) through application layer (Django apps and management commands), to persistence (database) and external integrations.
- Do not shy from breaking down the architecture into as many discrete components as the file tree indicates. This level of granularity (illustrating separate apps, settings, and environment controls) is crucial to correctly representing the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    HTTPReq["HTTP Request<br/>(http://localhost:8000/)"]:::external

    %% Infrastructure: Docker & Environment Management
    subgraph "Infrastructure"
        DEnv["Docker Environment"]:::infra
        subgraph "Docker Compose Configs"
            DComposeDev["Docker Compose (dev)"]:::infra
            DComposeProd["Docker Compose (prod)"]:::infra
            DComposeCI["Docker Compose (ci)"]:::infra
        end
        subgraph "Docker Scripts & Env Files"
            DockerDev["docker/.dev"]:::infra
            DockerProd["docker/.prod"]:::infra
            Dockerfile["Dockerfile"]:::infra
            Entrypoint["entrypoint.sh"]:::infra
            SetupPlagiarism["setup_plagiarism.py"]:::infra
        end
    end

    %% Django Backend Server
    subgraph "Django Backend Server"
        DjangoContainer["Django Container"]:::backend
        CoreProject["Core Project<br/>(src/core/)"]:::backend
        ManagePy["Project Management<br/>(src/manage.py)"]:::backend
    end

    %% Django Apps Layer
    subgraph "Django Apps"
        AuthApp["Authentication App<br/>(src/authentication/)"]:::app
        CoreApp["Core App"]:::app
        CoursesApp["Courses App"]:::app
        PlagApp["Plagiarism App"]:::app
        UsersApp["Users App<br/>(src/users/)"]:::app

        %% Core App Submodules
        subgraph "Core App Modules"
            CoreInv["Invitations<br/>(src/core/invitations/)"]:::app
            Locator["Locator<br/>(src/core/locator/)"]:::app
        end

        %% Courses App Submodules
        subgraph "Courses App Modules"
            CoursesInv["Invitations<br/>(src/courses/invitations/)"]:::app
            ProjectUpload["Project Uploading<br/>(src/courses/project_uploading/)"]:::app
        end

        %% Plagiarism App Submodules
        subgraph "Plagiarism App Modules"
            Vendor["Vendor (Tree-Sitter)<br/>(src/plagiarism/vendor/)"]:::externalDep
            PlagTest["Plagiarism Tests<br/>(src/plagiarism/test_plagiarism.py)"]:::app
            PlagMgmt["Management Command (Setup)<br/>(src/plagiarism/management/commands/setup_plagiarism.py)"]:::app
        end
    end

    %% Database
    Database["Database (PostgreSQL)"]:::database

    %% Relationships and Data Flow
    HTTPReq -->|"API_Request"| DEnv
    DEnv -->|"Container Runtime"| DjangoContainer
    DjangoContainer -->|"Loads"| CoreProject
    DjangoContainer -->|"Executes"| ManagePy

    DjangoContainer -->|"Routes to"| AuthApp
    DjangoContainer -->|"Routes to"| CoreApp
    DjangoContainer -->|"Routes to"| CoursesApp
    DjangoContainer -->|"Routes to"| PlagApp
    DjangoContainer -->|"Routes to"| UsersApp

    %% Core App internal connections
    CoreApp --- CoreInv
    CoreApp --- Locator

    %% Courses App internal connections
    CoursesApp --- CoursesInv
    CoursesApp --- ProjectUpload

    %% Plagiarism App internal connections
    PlagApp --- Vendor
    PlagApp --- PlagTest
    PlagApp --- PlagMgmt

    %% All Apps interact with the Database
    AuthApp -->|"ORM"| Database
    CoreApp -->|"ORM"| Database
    CoursesApp -->|"ORM"| Database
    PlagApp -->|"ORM"| Database
    UsersApp -->|"ORM"| Database

    %% Click Events for Docker & Environment Management
    click DComposeDev "https://github.com/kandeel4411/peam-backend/blob/main/docker-compose.dev.yml"
    click DComposeProd "https://github.com/kandeel4411/peam-backend/blob/main/docker-compose.prod.yml"
    click DComposeCI "https://github.com/kandeel4411/peam-backend/blob/main/docker-compose.ci.yml"
    click DockerDev "https://github.com/kandeel4411/peam-backend/blob/main/docker/.dev"
    click DockerProd "https://github.com/kandeel4411/peam-backend/blob/main/docker/.prod"
    click Dockerfile "https://github.com/kandeel4411/peam-backend/tree/main/docker/Dockerfile"
    click Entrypoint "https://github.com/kandeel4411/peam-backend/blob/main/docker/entrypoint.sh"
    click SetupPlagiarism "https://github.com/kandeel4411/peam-backend/blob/main/docker/scripts/setup_plagiarism.py"

    %% Click Events for Django Backend Server
    click CoreProject "https://github.com/kandeel4411/peam-backend/tree/main/src/core/"
    click ManagePy "https://github.com/kandeel4411/peam-backend/blob/main/src/manage.py"

    %% Click Events for Django Apps
    click AuthApp "https://github.com/kandeel4411/peam-backend/tree/main/src/authentication/"
    click CoreInv "https://github.com/kandeel4411/peam-backend/tree/main/src/core/invitations/"
    click Locator "https://github.com/kandeel4411/peam-backend/tree/main/src/core/locator/"
    click CoursesInv "https://github.com/kandeel4411/peam-backend/tree/main/src/courses/invitations/"
    click ProjectUpload "https://github.com/kandeel4411/peam-backend/tree/main/src/courses/project_uploading/"
    click PlagApp "https://github.com/kandeel4411/peam-backend/tree/main/src/plagiarism/"
    click Vendor "https://github.com/kandeel4411/peam-backend/tree/main/src/plagiarism/vendor/"
    click PlagTest "https://github.com/kandeel4411/peam-backend/blob/main/src/plagiarism/test_plagiarism.py"
    click PlagMgmt "https://github.com/kandeel4411/peam-backend/blob/main/src/plagiarism/management/commands/setup_plagiarism.py"
    click UsersApp "https://github.com/kandeel4411/peam-backend/tree/main/src/users/"

    %% Styling Classes
    classDef external fill:#ffdead,stroke:#d2691e,stroke-width:2px;
    classDef infra fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#006400,stroke-width:2px;
    classDef app fill:#ffffe0,stroke:#daa520,stroke-width:2px;
    classDef externalDep fill:#e0ffff,stroke:#20b2aa,stroke-width:2px;
    classDef database fill:#ffe4e1,stroke:#ff6347,stroke-width:2px;
```
