Služby

Sencai používá event-driven microservices architekturu, orchestrovanou přes Docker Compose (orchestration/). Každá služba má jasně vymezenou zodpovědnost. Tato stránka je index seskupený stejně jako samotné monorepo; pro hrstku nejsložitějších služeb existují detailní podstránky.

Core platforma

sencai.space

Role: Backend CMS / primární API — 212 content-types
Tech: Strapi v5, Node.js, TypeScript, MySQL
Port: 1337 (admin na 1337/admin)
Dokumentace: Strapi backend

sencai-backend

Role: Go strangler-fig náhrada sencai.space — parita content-type po content-type za stejným HTTP kontraktem, aby se provoz mohl postupně přesunout po jednotlivých routách. Shadow-only: nezapojeno do výchozích orchestračních profilů, neroutuje žádný reálný zákaznický provoz. Strapi zůstává jediný živý backend platformy.
Tech: Go, vlastní MySQL (go-backend-db, rozdělena z backend-db 2026-07-06)
Port: 8080 interně, host go-backend.sencai.localhost, profil go-backend (mimo DEFAULT_PROFILES)
Dokumentace: Migrace Go backendu — vývojářská reference

sencai.space-frontend

Role: UI platformy — auth flow a gravity dashboard (organizace, cloud instance)
Tech: Nuxt 3, Vue 3, Vuetify 3, Pinia
Port: 3000

sencai-web

Role: Veřejný marketingový web (sencai.space) — statický, 15 jazykových mutací
Tech: Astro 5 SSG, vanilla CSS, Three.js hero, servírováno přes nginx
Port: uvnitř kontejneru běží na nginx portu 80, dostupný přes Traefik host routing (sencai.localhost lokálně, sencai.space v produkci) — nemá vlastní surový dev port

sencai-audit

Role: Viewer SPA pro audit trail — neměnný event log per organizace
Tech: Nuxt 3, Keycloak OIDC (klient sencai-audit)
Port: 3300 · Host: audit.sencai.localhost
Dokumentace: Audit Trail

sencai-admin

Role: Interní admin dashboard — správa uživatelů a organizací
Tech: Nuxt 3, Vue 3, Keycloak OIDC
Port: 3100

api-manager

Role: Správa API tokenů a jejich šifrování
Tech: Fastify 5, TypeScript, AES-256-GCM
Port: 3200
Dokumentace: API Manager

Auth / Git / Webhook integrace

auth-service

Role: Konfigurace Keycloaku a vlastní témata (není běžící aplikace — konfigurační adresář konzumovaný kontejnerem keycloak)
Tech: Keycloak realm konfigurace, themes/
Port: samotný Keycloak naslouchá na 8180 (za /kc)
Dokumentace: Keycloak autentizace

auth-service-consumer

Role: RabbitMQ konzument — synchronizuje Strapi user/org události do Keycloaku, plus proces audit-consumer (hash-chained ukládání audit logu)
Tech: Node.js
RabbitMQ: odebírá exchange user a organisation; audit-consumer.js odebírá audit.events

webhook-publisher

Role: Přemosťuje Strapi webhooky do RabbitMQ
Tech: Koa (jediná záměrná výjimka z TypeScript konvence — čistý JavaScript)
Port: 1347
Dokumentace: Webhook Publisher

git-connector

Role: RabbitMQ konzument — synchronizuje Gitea repozitáře/organizace
Tech: Express, TypeScript
Port: 3002
RabbitMQ: odebírá git.events
Dokumentace: Git Connector

git-service

Role: Konfigurace instance Gitea — dvě oddělené instance: Toolbox (systémové repozitáře/šablony) a Apps (uživatelské aplikace)
Tech: Pouze konfigurace (upstream Gitea image), sdílená MySQL na portu 3308
Porty: Toolbox HTTP 9023 / SSH 9022, Apps HTTP 9034 / SSH 9033

Cloud / Infra

cloud-connector

Role: Multi-cloud provisioning — REST/SDK volání přímo na API providerů (AWS, GCP, Azure, Hetzner, DigitalOcean, Vultr, Linode), plus jeho worker proces odebírající cloud.events
Tech: TypeScript, TypeORM, PostgreSQL
Port: 4321
Dokumentace: Cloud Connector

infra-gcp

Role: CDKTF (Terraform CDK) IaC pro vlastní produkční multi-region infrastrukturu Sencai na GCP — není běžící služba, ale nástroj spouštěný při deployi
Tech: TypeScript, CDKTF
Port: n/a — není compose služba, nasazuje se nezávisle na orchestration/

k8s-agent

Role: Kubernetes fleet agent — Helm chart / manifesty pro spravované K8s clustery
Tech: Helm, Kubernetes manifesty
Port: n/a — není compose služba, nasazuje se nezávisle na orchestration/

Fleet / Agent / Opsloop

agent-gateway

Role: C2 (command-and-control) brána pro on-host fleet agenty — WebSocket + REST
Tech: Go
Port: 4400

sencai-agent

Role: On-host fleet agent binárka — monitoring, patch management, software inventář, spouštění runbooků
Tech: Go, distribuováno jako samostatná binárka (deb/rpm balíčkování, systemd unit), není Docker Compose služba
Port: n/a — komunikuje odchozím spojením směrem k agent-gateway

ssh-proxy-service

Role: Browser terminál — SSH/WebSocket proxy
Tech: Node.js, TypeScript
Port: 3400

opsloop-consumer

Role: OPSLOOP intelligence loop — RCA (root cause analysis) a návrhy remediace
Tech: Node.js, TypeScript
Port: 3005
RabbitMQ: odebírá alertmanager.events (routing key alert.firing)
Dokumentace: OPSLOOP

gamification-consumer

Role: Jediný writer content-typů user-rank/gamification-event (F4.GAM) — počítá změny XP/hodnosti/odznaků na straně serveru z platformní aktivity, nikdy nedůvěřuje hodnotě z příchozí zprávy
Tech: Node.js, TypeScript, Pino
Port: 3800 (jen health check)
RabbitMQ: odebírá gamification.events (topic); re-publikuje rank.up/badge.awarded/easter-egg.triggered na tentýž exchange pro frontendový notifikační most
Dokumentace: Gamification Consumer

forum-connector

Role: JIT (just-in-time) provisioning most mezi Keycloakem a sencai-forum (Lemmy) — při první návštěvě fóra automaticky založí Lemmy účet, synchronizuje KC roli forum-admin na Lemmy admina, pravidelně kontroluje Lemmy na nepřečtené odpovědi/zmínky a přeposílá je do notification-service, a automaticky vytvoří Lemmy komunitu při vzniku nové organizace ve Strapi
Tech: Fastify 5, TypeScript
Port: 4181
RabbitMQ: odebírá organisation.forum-community-requested; publikuje na notification.events
Dokumentace: Komunitní fórum — vývojářská reference

Billing / LLM / Notifikace / Eventy

billing-adapter

Role: Most mezi usage events a Lago (měření využití) a Stripe (platby)
Tech: Node.js, TypeScript
Port: 3600
Dokumentace: Billing Adapter

sencai-watchdog

Role: Dunning microservice — cron pro suspend/archive při selhání platby
Tech: Node.js, TypeScript
Port: 3700

llm-service

Role: LLM fasáda — multi-provider přístup k LLM pro platformu
Tech: Node.js, TypeScript
Port: 4430

notification-service

Role: Email + Slack konzument pro notification.events
Tech: Node.js, TypeScript

event-store-consumer

Role: Odebírá fanout platform.events a ingestuje události do Strapi
Tech: Node.js, TypeScript

workspace-connector

Role: Synchronizace Google Workspace Directory API
Tech: Node.js, TypeScript
Port: 3500

graphql-gateway

Role: GraphQL fasáda — sjednocené schéma nad Strapi REST API
Tech: Fastify 5, TypeScript, Apollo Server 5
Port: 4000
Dokumentace: GraphQL Gateway

Standalone / podpora

bootstrap

Role: Jednorázové bootstrap/seed skripty databáze pro Strapi
Tech: Node.js, TypeScript

sencai-mq

Role: Samostatný RabbitMQ broker, plus vlastní messaging konzumenti
Tech: RabbitMQ (upstream image)
Port: 5673 (AMQP), 15673 (management UI)

sencai-forum

Role: Komunitní fórum
Tech: Lemmy 0.19, sidecar oauth2-proxy pro Keycloak SSO
Port: Lemmy backend API 8536, oauth2-proxy 4180
Dokumentace: Komunitní fórum — vývojářská reference

backup-scheduler

Role: Denní zálohování MySQL do S3/GCS, plus obnovovací zkoušky (restore drills)
Tech: Node.js, TypeScript

sencai-docs

Role: Tato dokumentační stránka
Tech: Astro 5, Starlight, nginx

sencai-e2e

Role: End-to-end testovací sada proti živému orchestrovanému stacku
Tech: Playwright, TypeScript

Vyřazené služby

cloud-consumer a git-consumer (HTTP bridge konzumenti) byly odstraněny (ADR-001). Worker proces cloud-connector nyní odebírá cloud.events přímo; git synchronizaci zajišťuje výhradně git-connector. Na žádnou z vyřazených služeb se nemá odkazovat v nové dokumentaci.

RabbitMQ exchanges

Exchange	Typ	Poznámka
`user`	direct	Strapi user create/update → auth-service-consumer
`organisation`	direct	Strapi organisation create/update
`cloud.events`	topic	Cloud provisioning, odebírá cloud-connector worker
`git.events`	topic	Gitea sync, odebírá git-connector
`notification.events`	topic	Email/Slack dispatch, odebírá notification-service
`audit.events`	topic	Routing key `audit.write`; odebírá proces audit-consumer
`platform.events`	fanout	Všechny platformní eventy, odebírá event-store-consumer pro ingest do Strapi
`alertmanager.events`	topic	Monitoring alerty, routing key `alert.firing`, odebírá opsloop-consumer
`gamification.events`	topic	XP/hodnost/odznak aktivita, odebírá gamification-consumer (routing keys `xp.granted`, `badge.check`, `streak.tick`, `easter-egg.roll`)

Fallback fronty mají TTL 14 dní. Retry logika má strop 5 pokusů s exponenciálním backoff.

Databáze

Služba	Engine	Host	Dev port
Strapi backend	MySQL	`backend-db`	3306
Keycloak	MySQL	`keycloak-db`	3307
Gitea	MySQL	`git-service-mysql`	3308
Cloud Connector	PostgreSQL	`cloud-connector-db`	5434
Forum	PostgreSQL	`forum-db`	5435

Přehled portů

Služba	Port
Traefik	80, 8080
Strapi	1337
sencai.space-frontend	3000
sencai-audit	3300
sencai-admin	3100
API Manager	3200
Git Connector	3002
workspace-connector	3500
billing-adapter	3600
sencai-watchdog	3700
ssh-proxy-service	3400
opsloop-consumer	3005
gamification-consumer	3800
forum-connector	4181
graphql-gateway	4000
Cloud Connector	4321
agent-gateway	4400
llm-service	4430
Webhook Publisher	1347
RabbitMQ (sencai-mq)	5672 (AMQP), 15672 (UI) — standalone `sencai-mq` na 5673/15673
Keycloak	8180 (za `/kc`)
HashiCorp Vault	8200
Grafana	3000 (host `grafana.sencai.localhost`)
Gitea Toolbox	9023 (HTTP), 9022 (SSH)
Gitea Apps	9034 (HTTP), 9033 (SSH)

Kompletní architektonické detaily a datové toky viz kořenový CLAUDE.md.