Architecture
Kibegi divides responsibility by process and by domain. The entrypoint in cmd/kibegi-api composes infrastructure, app packages, routes, and middleware. Every domain package under internal/apps owns its own handler and repository behavior. The two Python services have narrow support roles and do not duplicate the domain layer.
Service topology
Internet → TLS reverse proxy → Go API :8080 → PostgreSQL / Redis / MinIO-S3
↘ private callback → AI indexer :8090
Internet → protected gateway → FastMCP / FastAPI agent :8091 → Go API :8080| Boundary | Owns | Does not own |
|---|---|---|
| Go API | HTTP contract, JWT, authorization, domain writes, cache invalidation | AI extraction loops or MCP session policy |
| AI indexer | Downloading objects, extraction, chunk persistence, retry state | Public domain routes or user authorization decisions |
| FastMCP gateway | Tool schema, route allowlist, confirmation gate, JWT forwarding | Database state, object storage, or user permissions |
Request path
The Go API wraps the multiplexer with request IDs, access logging, panic recovery, CORS, Redis-backed rate limiting, and timeout control. A protected handler validates the bearer token, obtains the user context, parses JSON or multipart input, calls a repository, commits durable state, invalidates caches, and returns the stable JSON envelope.
Failure isolation
Redis loss degrades cache and coordination but never becomes durable truth. MinIO/S3 loss blocks object operations. Indexer failure never turns a successful upload into an upload failure because the callback happens after commit. FastMCP gateway failure does not affect public API availability.
Read Operations for practical health, logging, backup, and rollback procedures.