# infinitewarp/quips architecture

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

- Interactive diagram: https://gitdiagram.com/infinitewarp/quips
- Repository: https://github.com/infinitewarp/quips

## Overview

##### Project type and purpose
- This is a full-stack, monolithic Django web application (“quips”) that serves HTML pages via Django’s “website” app, exposes a read-only REST API under `/quips/api/`, provides a CSV import management command for bulk data ingestion, and integrates with Slack via its “slackapp” module.
- It’s containerized with Docker Compose for Django/Gunicorn, Nginx, and PostgreSQL.

##### File structure
- Top-level:
- Docker and CI configs (`docker-compose.yml`, `compose/` subfolders, `.github/workflows/`, `gitlab-ci.yml`)
- Django project entrypoint (`manage.py`) and project settings under `config/`
- Main Django apps under `quips/`:
– `api/` (serializers, views, URLs, tests)
– `quips/` (core models, filters, stats, import command)
– `slackapp/` (Slack webhook handlers)
– `website/` (HTML views, templates, static assets)
- Static and template assets in `quips/static/` and `quips/templates/`.
- PostgreSQL scripts in `compose/postgres/`.
- Build/entry scripts for Docker in each `compose/` directory.

##### README for additional insights
- Local development uses `dev.yml` for Podman/Docker Compose, which stands up three containers: Django, Nginx, Postgres.
- A management command `importquips` loads CSV data into the database.
- The REST API exposes speaker and clique resources.

a. Main components
- Client (Browser or Slack)
- Nginx reverse proxy
- Gunicorn WSGI server running the Django project
- Django components (split into apps: website, API, slackapp, import command)
- PostgreSQL database
- External Slack API (for outgoing notifications or slash-command callbacks)

b. Relationships and interactions
1. Browser → HTTP → Nginx → HTTP → Gunicorn → Django “website” or “api” apps → ORM queries → PostgreSQL
2. Slack platform ↔ HTTP webhooks → Nginx → Gunicorn → Django “slackapp” endpoints
3. `importquips` executed inside the Django container reads CSV → invokes Django ORM → writes to PostgreSQL
4. Static files served directly by Nginx from `/static/` mapped volume

c. Architectural patterns and design principles
- Monolithic MVC (Django): models in `quips/quips/models.py`, views/serializers per app, URL routing in each app
- Twelve-factor app principles: containers, config via env vars, separate build/run stages (`Dockerfile`, entrypoint scripts)
- Clear separation between runtime (Gunicorn) and reverse proxy (Nginx)

d. Key technologies and frameworks
- Python 3 / Django
- Gunicorn (WSGI)
- Nginx (reverse proxy + static file server)
- PostgreSQL
- Docker Compose for orchestration
- GitHub Actions / GitLab CI for CI/CD

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Clients"
    BROWSER["Browser"]:::client
    SLACK_CLIENT["Slack Platform"]:::client
  end

  subgraph "Docker Compose Orchestration"
    DC["Docker Compose"]:::orch
  end

  subgraph "Containers"
    subgraph "Nginx Container"
      NGINX["Nginx"]:::service
    end

    subgraph "Django Container"
      GUNICORN["Gunicorn + Django"]:::service
      subgraph "Django Apps"
        WEB["Website App"]:::app
        API["REST API App"]:::app
        SLACK["Slack Integration App"]:::app
        CORE["Core Quips App"]:::app
      end
      IMPORT["importquips (CLI)"]:::cli
    end

    subgraph "PostgreSQL Container"
      PG["PostgreSQL"]:::db
    end
  end

  subgraph "Configuration"
    CI["CI/CD Config"]:::config
    ENV["Env & Dependencies"]:::config
    TESTCFG["Test Config"]:::config
  end

  subgraph "External"
    EXTSLACK["Slack API"]:::external
  end

  %% Flows
  BROWSER -->|"HTTP Request"| NGINX
  NGINX -->|"Proxy HTTP"| GUNICORN
  GUNICORN -->|"Serves HTML"| WEB
  GUNICORN -->|"REST API"| API
  GUNICORN -->|"Slack Webhook"| SLACK
  GUNICORN -->|"ORM Queries"| PG
  PG -->|"ORM Response"| GUNICORN
  GUNICORN -->|"CLI Command"| IMPORT
  IMPORT -.->|"Writes CSV Data"| PG
  NGINX -->|"Serves Static"| BROWSER

  SLACK_CLIENT -->|"Webhook Events"| NGINX
  SLACK -->|"Call Slack API"| EXTSLACK
  EXTSLACK -->|"Callback"| SLACK

  DC --> NGINX
  DC --> GUNICORN
  DC --> PG
  DC --> CI
  DC --> ENV

  %% Click Events
  click DC "https://github.com/infinitewarp/quips/blob/main/docker-compose.yml"
  click NGINX "https://github.com/infinitewarp/quips/tree/main/compose/nginx/Dockerfile"
  click GUNICORN "https://github.com/infinitewarp/quips/tree/main/compose/django/Dockerfile"
  click PG "https://github.com/infinitewarp/quips/tree/main/compose/postgres/Dockerfile"
  click GUNICORN "https://github.com/infinitewarp/quips/blob/main/manage.py"
  click API "https://github.com/infinitewarp/quips/blob/main/quips/api/serializers.py"
  click WEB "https://github.com/infinitewarp/quips/blob/main/quips/website/views.py"
  click SLACK "https://github.com/infinitewarp/quips/blob/main/quips/slackapp/views.py"
  click CORE "https://github.com/infinitewarp/quips/blob/main/quips/quips/models.py"
  click IMPORT "https://github.com/infinitewarp/quips/blob/main/quips/quips/management/commands/importquips.py"
  click CI "https://github.com/infinitewarp/quips/blob/main/.github/workflows/build.yml"
  click ENV "https://github.com/infinitewarp/quips/blob/main/env.example"
  click TESTCFG "https://github.com/infinitewarp/quips/blob/main/pytest.ini"

  %% Styles
  classDef orch fill:#90bfff,stroke:#333,stroke-width:1px
  classDef service fill:#8ecae6,stroke:#333,stroke-width:1px
  classDef db fill:#a0c661,stroke:#333,stroke-width:1px
  classDef external fill:#f4a261,stroke:#333,stroke-width:1px
  classDef client fill:#cccccc,stroke:#333,stroke-width:1px
  classDef app fill:#e0fbfc,stroke:#333,stroke-width:1px
  classDef cli fill:#dddddd,stroke:#333,stroke-width:1px
  classDef config fill:#f0f0f0,stroke:#333,stroke-width:1px
```
