Project Overview

This page is for developers and contributors. If you’re looking for how to use Citinet, start with Getting Started instead.

The guiding principle

Citinet’s architecture follows one rule: centralize only the on-ramp, decentralize everything downstream. A small set of shared services exist to make hub creation and discovery easy; everything a running hub actually needs (data, governance, moderation) lives entirely on that hub’s own infrastructure. See Core Concepts for the user-facing version of this, and The Cert Broker for the clearest concrete example of it in practice.

Split across repositories

Rather than one monolithic codebase, Citinet is split by concern across several repositories. See Repositories for the full list. Each deploys independently.

The hub stack

A single hub runs as a small set of Docker containers: the API/portal server, a Postgres database, MinIO for file storage, Redis, an optional local Ollama instance for AI features, and Caddy for TLS termination. All of it is generated and configured automatically by the setup script a hub operator downloads from the creation wizard. See Creating a Hub for the operator-facing version.

Centralized services

Two things are centrally operated, both deliberately minimal in scope:

• The registry: an optional, opt-in directory of publicly listed hubs.
• The cert broker: issues and renews HTTPS certificates for hubs automatically. See The Cert Broker.

Both are designed as swappable service boundaries (a clear API and clear, dedicated service credentials) specifically so operating them could move from a single maintainer to a shared/delegated model later without a rewrite.