# hawk-digital-environments/hawki architecture

> Architecture diagram of the GitHub repository hawk-digital-environments/hawki, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hawk-digital-environments/hawki
- Repository: https://github.com/hawk-digital-environments/hawki

## Overview

##### Project type and purpose
- This is a full-stack, monolithic web application built on the Laravel framework.
- Purpose: HAWKI2 is a data-protection compliant AI-assisted group-chat and collaboration platform for universities, with modular AI-model integration (OpenAI, Google, GWDG, Ollama, etc.), export/summarization, and peer-to-peer rooms.

##### File structure
- Top-level “app/” directory holds the Laravel MVC backend:
- Http/Controllers → request handling (API, web)
- Models → Eloquent ORM objects (User, Room, Message, AiConv, etc.)
- Services → domain logic (AI providers, Auth integrations, UsageAnalyzer)
- Jobs & Events → background processing and broadcasting
- “resources/views” + “resources/js/css” + “public/…” = frontend presentation layer (Blade templates, vanilla JS/CSS, Vite build).
- “routes/” defines API/web/console endpoints.
- “config/” and “bootstrap/” hold environment config and framework initialization.
- “database/” for migrations and seeding; default DB is relational (MySQL/Postgres).
- Docker-related folders (“docker/”, “_docker_production/”) contain NGINX, PHP-FPM, Node build, and deployment orchestration.
- Included CLI scaffolding under “bin/_env” for environment management (developer tooling, not part of runtime architecture).

##### README for additional insights
- Emphasis on group chat rooms, integrated AI agents, summarization/export, and modular AI backends.

##### Elements
- Component labels: “Browser UI”, “NGINX Reverse Proxy”, “Laravel App (PHP-FPM)”, “Database”, “Storage”, “Queue Worker”, “AI Provider X”, etc.
- Blue rectangles for containers/services
- Orange clouds for external services

##### Detail—capture all runtime pieces
- Separate containers for web/proxy, app, worker, DB, cache.
- Directories in the codebase (app/Services, app/Http/Controllers) next to each backend component to tie code to runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    BrowserUI["Browser UI"]:::service
    click BrowserUI "https://github.com/hawk-digital-environments/hawki/blob/main/resources/js/app.js"

    %% Edge / Ingress
    NGINX["NGINX Reverse Proxy"]:::service
    click NGINX "https://github.com/hawk-digital-environments/hawki/blob/main/docker/nginx/config/nginx.dev.conf"

    %% Application Layer
    subgraph "Application Layer"
        LaravelApp["Laravel App (PHP-FPM)"]:::service
        click LaravelApp "https://github.com/hawk-digital-environments/hawki/blob/main/bootstrap/app.php"

        subgraph "Service Layer"
            AIService["AI Integration Service"]:::service
            click AIService "https://github.com/hawk-digital-environments/hawki/blob/main/app/Services/AI/AIConnectionService.php"
            AuthService["Authentication Service"]:::service
            click AuthService "https://github.com/hawk-digital-environments/hawki/blob/main/app/Services/Auth/LdapService.php"
        end

        QueueWorker["Queue Worker / Jobs"]:::service
        click QueueWorker "https://github.com/hawk-digital-environments/hawki/blob/main/app/Jobs/SendMessage.php"
        Events["Events & Broadcasting"]:::service
        click Events "https://github.com/hawk-digital-environments/hawki/blob/main/app/Events/RoomMessageEvent.php"
        MailService["Mail Service"]:::service
        click MailService "https://github.com/hawk-digital-environments/hawki/blob/main/app/Mail/GeneralMail.php"
    end

    %% Data Layer
    Database["Relational Database"]:::datastore
    click Database "https://github.com/hawk-digital-environments/hawki/tree/main/database/migrations/"
    Storage["File Storage"]:::datastore
    click Storage "https://github.com/hawk-digital-environments/hawki/tree/main/storage/app/public/"
    CacheStore["Cache / Session Store"]:::datastore
    click CacheStore "https://github.com/hawk-digital-environments/hawki/blob/main/config/cache.php"

    %% Infrastructure / DevOps
    subgraph "Infrastructure (Docker Compose)" 
        DockerCompose["Docker Compose Orchestration"]:::infra
        click DockerCompose "https://github.com/hawk-digital-environments/hawki/blob/main/docker-compose.yml"
        CICD["CI/CD Workflow"]:::infra
        click CICD "https://github.com/hawk-digital-environments/hawki/blob/main/.github/workflows/publish-dockerimage.yml"
    end

    %% External Services
    subgraph "External"
        AIProviders["AI Model Providers"]:::external
        AuthExt["Auth Providers (LDAP/OIDC/Shibboleth)"]:::external
        MailExt["SMTP / Mailhog"]:::external
    end

    %% Connections
    BrowserUI -->|"HTTPS"| NGINX
    NGINX -->|"FastCGI"| LaravelApp
    LaravelApp -->|"SQL"| Database
    LaravelApp -->|"Read/Write"| Storage
    LaravelApp -->|"Get/Set"| CacheStore
    LaravelApp -->|"Dispatch Jobs"| QueueWorker
    QueueWorker -->|"HTTP REST"| AIProviders
    QueueWorker -->|"SMTP"| MailExt
    LaravelApp -->|"Broadcast Events"| Events
    Events -->|"WebSockets"| BrowserUI
    LaravelApp -->|"LDAP/OIDC/Shib"| AuthExt

    %% Styles
    classDef service fill:#ADD8E6,stroke:#000;
    classDef datastore fill:#90EE90,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
    classDef infra fill:#F0E68C,stroke:#000;
```
