Start with the service map

Kibegi is a Go-primary backend with two focused Python support services. The Go API owns public contracts, authorization, database writes, Redis coordination, object storage, and provider calls. The AI indexer handles asynchronous document work. The FastMCP gateway makes the API available to trusted agent clients without replacing Go authorization.

Operating rule: PostgreSQL is durable truth, Redis accelerates and coordinates, MinIO/S3 holds objects, and the Go API remains the final authority for every domain decision.

Bring the stack up in order

Order	Service	Default port	Why it starts here
1	PostgreSQL, Redis, MinIO/S3	private	Every Kibegi service depends on durable data, coordination, or objects.
2	Go API	`8080`	It owns the public contract and sends post-upload callbacks.
3	FastAPI AI indexer	`8090`	It needs PostgreSQL, object storage, and the Go callback token.
4	FastAPI/FastMCP gateway	`8091`	It forwards requests to the reachable Go API.

First verification


# Go service
GOTOOLCHAIN=local go test ./...
GOTOOLCHAIN=local go build -o bin/kibegi-api ./cmd/kibegi-api/
 
# Python support services
python3 -m compileall -q services/ai-indexer/app services/kibegi-agent/app
PYTHONPATH=services/ai-indexer pytest -q services/ai-indexer/tests
PYTHONPATH=services/kibegi-agent pytest -q services/kibegi-agent/tests

Use GET /api/v1/health/ for Go readiness, GET /health for the indexer, and GET /health for the gateway. A private dependency failure should be visible in the health payload rather than hidden behind a successful-looking deployment.

Continue with Architecture to understand dependencies, Go API reference to integrate an application, AI indexer to operate ingestion, or Agent & FastMCP to connect a tool-using client.