Architektúra systému¶

Overené podľa implementácie dňa 2026-05-07.

Runtime architektúra¶

flowchart LR
    subgraph Edge["Edge vrstva"]
        Caddy["Caddy :80/:443"]
    end

    subgraph App["Aplikačná vrstva"]
        API["FastAPI\n/api/v1 + /dashboard"]
        W["RQ Worker\nhigh / default / low"]
        SCH["rq-scheduler"]
    end

    subgraph Data["Dátová vrstva"]
        PG[("PostgreSQL 16")]
        RD[("Redis 7")]
    end

    subgraph Ext["Externé"]
        GL["GitLab"]
    end

    subgraph Obs["Pozorovateľnosť"]
        Prom["Prometheus"]
        Graf["Grafana"]
        J["Jaeger"]
    end

    GL -->|"Webhook + OAuth + API"| Caddy
    Caddy --> API
    API --> PG
    API --> RD
    RD --> W
    SCH --> RD
    W --> PG
    W --> GL
    API --> Prom
    Prom --> Graf
    API -. "OTLP" .-> J
    W -. "OTLP" .-> J

Komponenty a zodpovednosti¶

Asynchrónny pipeline (webhook -> metriky)¶

sequenceDiagram
    participant GL as GitLab
    participant API as FastAPI
    participant DB as PostgreSQL
    participant RQ as Redis/RQ
    participant W as Worker

    GL->>API: POST /api/v1/webhooks/gitlab
    API->>API: verify X-Gitlab-Token
    API->>DB: store raw event
    API->>RQ: enqueue process_event (high)
    API-->>GL: 202 accepted

    RQ->>W: dequeue process_event
    W->>DB: upsert entities
    W->>RQ: enqueue enrichment/metrics (default)

    RQ->>W: dequeue compute_metrics
    W->>DB: save MetricSnapshot

Architektúra autentifikácie¶

flowchart TB
    U["Používateľ"] -->|"/dashboard/login"| OAuth["GitLab OAuth"]
    OAuth -->|callback| Sess["gitpulse_session cookie"]
    Sess --> Dash["/dashboard/..."]

    APIClient["API klient"] -->|"Authorization Bearer"| ApiAuth["/api/v1/..."]
    Sess -->|"alternatívne"| ApiAuth

    GitLabWH["GitLab webhook"] -->|"X-Gitlab-Token"| WH["/api/v1/webhooks/gitlab"]

Autentifikačné vrstvy:

1. Dashboard: GitLab OAuth + podpísaná session cookie.
2. API: Bearer token (TEACHER_API_TOKEN) alebo dashboard session.
3. Webhook endpoint: per-project secret (X-Gitlab-Token).

Queue a plánované úlohy¶

Periodické joby (22 naplánovaných úloh, všetky gate-ované feature flagmi):

• sweep_unprocessed_events (každých 15 min) - opakovanie nespracovaných webhookov
• sweep_expired_ci_scenarios (každých 15 min) - auto-rollback CI scenárov
• periodic_enrich_all (každé 4 hodiny) - re-fetch issues a MR z GitLabu
• periodic_metrics_all (každú 1 hodinu) - prepočet compliance metrík
• cleanup_old_reports (každých 24 hodín) - mazanie starých reportov
• periodic_membership_sync (každé 2 hodiny) - sync členov tímov z GitLabu
• sweep_expired_conflict_challenges (každú 1 hodinu) - expirácia konfliktov
• sweep_unverified_conflicts (každých 30 min) - overenie riešení konfliktov
• sweep_stale_projects (každú 1 hodinu) - re-fetch dát pre neaktívne projekty
• periodic_llm_analysis (každých 6 hodín) - LLM analýza otvorených MR
• periodic_telemetry_snapshot (každých 24 hodín) - týždenné compliance snapshoty
• sweep_stale_background_jobs (každých 24 hodín) - cleanup zaseknutých jobov
• sweep_dlq_auto_resurrect - auto-retry dead-letter queue udalostí
• periodic_docker_reverify (každých 24 hodín) - re-analýza Dockerfilov
• periodic_enrich_users (každých 24 hodín) - refresh používateľských profilov z GitLabu
• periodic_verify_webhooks - overenie registrácie webhookov
• sweep_dead_projects (každých 24 hodín) - detekcia nedostupných projektov
• cleanup_old_events (každých 24 hodín) - mazanie starých spracovaných webhookov
• cleanup_old_metric_snapshots (každých 24 hodín) - mazanie snapshotov starších ako 180 dní
• cleanup_old_audit_logs (každých 24 hodín) - mazanie audit logov starších ako 180 dní
• sweep_discover_new_projects - automatické objavenie nových projektov v GitLab grupách
• sweep_email_queue (každé 2 min) - odosielanie čakajúcich emailov

Deployment model¶

Produkčný profil používa Docker Compose služby:

• postgres
• redis
• api
• worker
• scheduler
• caddy

Voliteľný profil monitoring pridáva:

• prometheus
• grafana
• jaeger

Súvisiace stránky¶

• API referencia
• Monitoring
• Nasadenie