# med-mostapha/gestion-de-stock-intelligent-django architecture

> Architecture diagram of the GitHub repository med-mostapha/gestion-de-stock-intelligent-django, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/med-mostapha/gestion-de-stock-intelligent-django
- Repository: https://github.com/med-mostapha/gestion-de-stock-intelligent-django

## Overview

##### What this project is (type + purpose)
This repository is a **backend-only Django REST API** (“Gestion de Stock Intelligent API”) for **inventory management** with:
- **Authentication** (Token and/or JWT per README)
- **User-isolated data model**: Users own Categories; Categories contain Products
- **Business endpoints**: CRUD for categories/products + computed endpoints for **alerts** (low stock, expired) and a **dashboard** inventory summary.

##### What the file tree says about architecture
Top-level structure:
- `config/` = **Django project** (global settings/urls/asgi/wsgi)
- `settings.py`: environment, installed apps, middleware, DB, auth configuration
- `urls.py`: global routing entrypoint (likely mounts `/api/`)
- `asgi.py`/`wsgi.py`: deployment entrypoints
- `accounts/` = **single Django app** containing almost all domain logic
- `models.py`: domain entities (Category, Product, and likely User usage)
- `serializers.py`: DRF serialization + validation + computed fields
- `views.py`: DRF views/viewsets + custom endpoints (alerts, dashboard, auth)
- `urls.py`: app-level routes (register/login/categories/products/alerts/dashboard)
- `admin.py`: admin registration (not runtime critical, but useful for ops/admin)
- `migrations/`: schema evolution proving the DB-backed nature
- `manage.py`: local management entrypoint
- `.env.example`: environment variables (DB creds, secret key, JWT settings, etc.)
- `requirements.txt`: dependency set (Django, djangorestframework, auth libs, etc.)

Architecturally, this is a **monolithic Django service** with a clear DRF layering:
**URLs → Views → Serializers → Models → Database**
and cross-cutting concerns:
**Authentication/Permissions** + **Queryset filtering for tenant isolation**.

##### What the README adds (runtime responsibilities)
The README is very explicit about:
- **Tenant isolation rule**: queries filtered by `category__owner=request.user`
- **Endpoints**:
- `/api/register/`, `/api/login/`
- `/api/categories/` (CRUD)
- `/api/products/` (CRUD)
- `/api/products/alerts/` (computed)
- `/api/dashboard/` (aggregated analytics)
- **Alert logic**:
- low stock: `quantity <= min_threshold` (DB-level via `F()` expressions)
- expired: `expiration_date <= today` with timezone awareness

- **Core invariants** (user scoping / ownership enforcement)
- **Data flows** from client → API endpoints → DB queries/aggregations → response.

##### Context (C4 L1): who/what talks to the system
3) **Component (C4 L3)**: Django internals (routing, views, serializers, models) and key endpoints.

This project is small enough that showing all three keeps it “detailed” without becoming noisy.

**Main components**
- **Client(s)**: “Web/Mobile Frontend Dashboard” (external)
- **Gestion de Stock API (Django/DRF)**: this repo

**Relationships**
- Client → API over HTTPS/JSON REST
- API → DB via Django ORM

**Important notes to annotate**
- Auth header modes: `Authorization: Token …` or `Bearer …`
- “User-isolated data access enforced server-side”

##### API Server
- Django + Django REST Framework
- Runs via `gunicorn` (WSGI) or ASGI server (if used later); repo includes both entrypoints.
- Exposes `/api/*`

##### Database
- Persistent relational store holding `auth_user`, `Category`, `Product` tables (plus migrations)

- **Reverse proxy** (Nginx) in front of API (common production)
- **Email provider** (future “Email alerts”)
- **Scheduler/Worker** (Celery/cron) if alerts become push-based (currently alerts are computed on GET)

**Interactions**
- Client → Reverse Proxy → Django API
- Django API ↔ DB (read/write for CRUD; read/aggregate for alerts/dashboard)

**Key constraints to label**
- Stateless API (token/JWT auth)
- Multi-tenant-by-filtering (per-request scoping)

##### Routing
- `config/urls.py` (project router)
- mounts `accounts/urls.py` under `/api/` (likely)
- `accounts/urls.py`
- maps to views: register, login, categories, products, alerts, dashboard

##### API Layer
- `accounts/views.py`
- Auth endpoints: Register/Login
- Category endpoints: List/Create/Update/Delete
- Product endpoints: List/Retrieve/Create/Update/Delete
- Alerts endpoint: `/products/alerts/`
- Dashboard endpoint: `/dashboard/`

##### Serialization/Validation
- `accounts/serializers.py`
- Transforms Category/Product to JSON
- Adds computed fields (`is_low_stock`, `has_expiry`)
- Validates payload (price, quantity, category ownership, etc.)

##### Domain/Data Model
- `accounts/models.py`
- `Category(owner FK User, name, created_at, …)`
- `Product(category FK Category, name, price, quantity, min_threshold, expiration_date, created_at, …)`
- DB tables derived from migrations: `accounts/migrations/000*_*.py`

##### Cross-cutting
- Authentication/permissions configured in `config/settings.py`
- Ownership enforcement occurs in views/querysets:
- `Category.objects.filter(owner=request.user)`
- `Product.objects.filter(category__owner=request.user)` (explicitly called out in README)

- Request → `config/urls.py` → `accounts/urls.py` → `accounts/views.py`
- View → Serializer (validate/serialize)
- View/Serializer → Model/ORM → DB
- DB → ORM → View → Response JSON

**Highlight “computed endpoints”**
- Alerts: ORM queries with `F()` comparisons + date filtering
- Dashboard: ORM aggregations (counts, sums, group-by category)

**External**
- Frontend Dashboard (Web/Mobile)
- (Optional) Admin user via Django Admin

**API**
- Django REST API (`manage.py` runtime; deployed via WSGI/ASGI)
- Auth module (register/login)
- Category API
- Product API
- Alerts API
- Dashboard API

**Internal layers**
- `config/urls.py` + `accounts/urls.py`
- `accounts/views.py`
- `accounts/serializers.py`
- `accounts/models.py`

**Data store**
- RDBMS storing Users/Categories/Products

**Key annotations**
- `/api/*` base path
- Auth required except register/login
- Isolation rule: `category__owner=request.user`
- Alert rules: low stock (`quantity <= min_threshold`), expired (`expiration_date <= today`)

##### Container: Reverse proxy (optional) → Django API (WSGI/ASGI) → DB
3. **Component**: `urls → views → serializers → models → DB` plus endpoint groupings (Auth/Categories/Products/Alerts/Dashboard) and the ER relationship.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% L1: System Context
  %% =========================
  subgraph "L1 — System Context"
    direction TB

    Client["Client App\n(Web/Mobile Dashboard)"]:::external
    AdminUser["Admin User\n(Django Admin)"]:::external

    subgraph "Server-side Trust Boundary"
      direction TB
      API["Gestion de Stock Intelligent API\n(Django REST Framework)"]:::api
      DB[("Relational Database\n(Users, Categories, Products)")]:::db
    end

    Client -->|"HTTPS_JSON_REST\nAuthorization:Token_or_Bearer"| API
    AdminUser -->|"HTTPS_Admin"| API
    API -->|"ORM_SQL"| DB

    NoteIso["Invariant:\nUser-isolated data access\nCategory.owner = request.user\nProduct.category.owner = request.user"]:::note
    API -.->|"enforces"| NoteIso
  end

  %% =========================
  %% L2: Container / Runtime
  %% =========================
  subgraph "L2 — Container / Runtime View"
    direction TB

    Client2["Client App"]:::external

    subgraph "Runtime"
      direction TB
      RP["Reverse Proxy\n(Optional: Nginx)"]:::infra
      subgraph "Django API Server"
        direction TB
        WSGI["WSGI App Entrypoint"]:::runtime
        ASGI["ASGI App Entrypoint"]:::runtime
        DRF["Django + DRF\nStateless REST API"]:::api
      end
      DB2[("Relational Database\nPersistent Store")]:::db
    end

    Client2 -->|"HTTPS_JSON_REST"| RP
    RP -->|"forward_/api/*"| DRF
    WSGI -->|"serves"| DRF
    ASGI -->|"serves"| DRF
    DRF -->|"ORM_SQL\nCRUD + Queries + Aggregations"| DB2

    NoteAuth["Auth:\nRegister/Login public\nOthers require Token/JWT"]:::note
    DRF -.->|"uses"| NoteAuth
  end

  %% =========================
  %% L3: Component / Code Structure
  %% =========================
  subgraph "L3 — Component / Django Internals"
    direction TB

    subgraph "Project (config/)"
      direction TB
      CFG_URLS["config/urls.py\nGlobal Router\n(mounts /api/)"]:::router
      CFG_SETTINGS["config/settings.py\nSettings: Apps, Middleware,\nAuth, DB, DRF"]:::config
      CFG_WSGI["config/wsgi.py\nDeployment Entrypoint"]:::runtime
      CFG_ASGI["config/asgi.py\nDeployment Entrypoint"]:::runtime
    end

    MGMT["manage.py\nManagement Entrypoint\n(runserver, migrate, createsuperuser)"]:::tool

    subgraph "Core App (accounts/)"
      direction TB
      ACC_DIR["accounts/\nDomain App Boundary"]:::group

      ACC_URLS["accounts/urls.py\nApp Routes"]:::router

      subgraph "API Layer"
        direction TB
        VIEWS["accounts/views.py\nDRF Views/ViewSets\n(Auth + Inventory + Computed Endpoints)"]:::component

        subgraph "Endpoints / Capabilities"
          direction TB
          EP_AUTH["/api/register/\n/api/login/"]:::endpoint
          EP_CAT["/api/categories/\nCRUD"]:::endpoint
          EP_PROD["/api/products/\nCRUD"]:::endpoint
          EP_ALERTS["/api/products/alerts/\nComputed: low_stock + expired"]:::endpoint
          EP_DASH["/api/dashboard/\nAggregated inventory summary"]:::endpoint
        end
      end

      SER["accounts/serializers.py\nSerialization + Validation\n(computed fields)"]:::component
      MOD["accounts/models.py\nDomain Models\nUser → Category → Product"]:::component
      MIG["accounts/migrations/\nSchema Evolution"]:::component
      ADM["accounts/admin.py\nAdmin Registration"]:::component
    end

    ENV[".env.example\nEnvironment Template\n(secrets, DB, JWT)"]:::config
    REQ["requirements.txt\nDependencies\n(Django, DRF, Auth libs)"]:::config
    DOC["README.md\nEndpoints + Rules\n(Isolation, Alerts, Dashboard)"]:::doc

    DB3[("Database Tables\nauth_user, Category, Product")]:::db

    %% Request flow
    Client3["HTTP Client"]:::external
    Client3 -->|"HTTPS_/api/*"| CFG_URLS
    CFG_URLS -->|"include()_accounts"| ACC_URLS
    ACC_URLS -->|"route_to"| VIEWS
    VIEWS -->|"validate_serialize"| SER
    VIEWS -->|"ORM_access"| MOD
    MOD -->|"SQL"| DB3
    DB3 -->|"results"| MOD
    MOD -->|"querysets"| VIEWS
    SER -->|"JSON_response"| VIEWS

    %% Capabilities to views
    ACC_URLS -->|"maps"| EP_AUTH
    ACC_URLS -->|"maps"| EP_CAT
    ACC_URLS -->|"maps"| EP_PROD
    ACC_URLS -->|"maps"| EP_ALERTS
    ACC_URLS -->|"maps"| EP_DASH
    EP_AUTH -->|"handled_by"| VIEWS
    EP_CAT -->|"handled_by"| VIEWS
    EP_PROD -->|"handled_by"| VIEWS
    EP_ALERTS -->|"handled_by"| VIEWS
    EP_DASH -->|"handled_by"| VIEWS

    %% Cross-cutting notes
    NoteFilter["Tenant Isolation:\nCategory.objects.filter(owner=request.user)\nProduct.objects.filter(category__owner=request.user)"]:::note
    VIEWS -.->|"filtered_querysets"| NoteFilter

    NoteAlerts["Alerts Logic:\nlow_stock: quantity <= min_threshold (F())\nexpired: expiration_date <= today (timezone-aware)"]:::note
    EP_ALERTS -.->|"computes"| NoteAlerts

    NoteDash["Dashboard:\nAggregation queries\n(counts/sums/group-by)"]:::note
    EP_DASH -.->|"aggregates"| NoteDash

    %% Mini-ER
    subgraph "Data Model (ER Mini)"
      direction TB
      ER_USER["User"]:::er
      ER_CAT["Category\n(owner FK User)"]:::er
      ER_PROD["Product\n(category FK Category)"]:::er
      ER_USER -->|"1..N"| ER_CAT
      ER_CAT -->|"1..N"| ER_PROD
    end
    MOD -.->|"implements"| ER_USER
    MOD -.->|"implements"| ER_CAT
    MOD -.->|"implements"| ER_PROD

    %% Settings influence
    CFG_SETTINGS -.->|"configures"| VIEWS
    CFG_SETTINGS -.->|"configures"| MOD
    ENV -.->|"provides_env_vars"| CFG_SETTINGS
    REQ -.->|"installs"| DRF
    DOC -.->|"documents"| ACC_URLS

    %% Admin path
    ADM -->|"registers_models"| MOD
    AdminUser2["Admin User"]:::external
    AdminUser2 -->|"admin_site"| ADM

    %% Deployment entrypoints relationship
    CFG_WSGI -->|"loads_settings"| CFG_SETTINGS
    CFG_ASGI -->|"loads_settings"| CFG_SETTINGS
    MGMT -->|"uses"| CFG_SETTINGS
    MGMT -->|"executes_migrations"| MIG
    MIG -->|"creates_tables"| DB3
  end

  %% =========================
  %% Click events (from mapping)
  %% =========================
  click CFG_SETTINGS "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/config/settings.py"
  click CFG_URLS "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/config/urls.py"
  click CFG_ASGI "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/config/asgi.py"
  click CFG_WSGI "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/config/wsgi.py"
  click MGMT "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/manage.py"

  click ACC_DIR "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/tree/main/accounts/"
  click MOD "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/accounts/models.py"
  click MIG "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/tree/main/accounts/migrations/"
  click SER "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/accounts/serializers.py"
  click VIEWS "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/accounts/views.py"
  click ACC_URLS "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/accounts/urls.py"
  click ADM "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/accounts/admin.py"

  click ENV "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/.env.example"
  click REQ "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/requirements.txt"
  click DOC "https://github.com/med-mostapha/gestion-de-stock-intelligent-django/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#1f77b4,stroke:#0b2d4a,color:#ffffff,stroke-width:1px
  classDef api fill:#2ca02c,stroke:#1b5e20,color:#ffffff,stroke-width:1px
  classDef db fill:#7f7f7f,stroke:#424242,color:#ffffff,stroke-width:1px
  classDef infra fill:#5dade2,stroke:#1b4f72,color:#ffffff,stroke-width:1px
  classDef router fill:#f39c12,stroke:#6e2c00,color:#ffffff,stroke-width:1px
  classDef component fill:#e67e22,stroke:#6e2c00,color:#ffffff,stroke-width:1px
  classDef endpoint fill:#d35400,stroke:#6e2c00,color:#ffffff,stroke-width:1px
  classDef config fill:#8e44ad,stroke:#3d1a52,color:#ffffff,stroke-width:1px
  classDef tool fill:#16a085,stroke:#0b5345,color:#ffffff,stroke-width:1px
  classDef doc fill:#2c3e50,stroke:#1b2631,color:#ffffff,stroke-width:1px
  classDef note fill:#f7dc6f,stroke:#7d6608,color:#111111,stroke-width:1px
  classDef group fill:#f0b27a,stroke:#6e2c00,color:#111111,stroke-width:1px
  classDef runtime fill:#27ae60,stroke:#145a32,color:#ffffff,stroke-width:1px
  classDef er fill:#fadbd8,stroke:#922b21,color:#111111,stroke-width:1px
```
