Federation

Federation is the server-side runtime container that manages Service lifecycle, auth, and HTTP routing.

Federation is the server-side core instance (formerly called "City runtime" in older docs). It encapsulates HTTP routing, auth, env vars, and database infrastructure. The client-side entry is City; do not confuse the two.

Minimal Usage

import { Federation } from "@downcity/city";

const base = new Federation({ db });

Service Registration

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { AIService, Provider, type OpenAICompatibleClientConfig } from "@downcity/city";

class DeepSeekProvider extends Provider {
  constructor() {
    super({
      id: "deepseek",
      baseURL: "https://api.deepseek.com",
      envKey: "DEEPSEEK_API_KEY",
    });
  }

  protected createClient({ apiKey, baseURL }: OpenAICompatibleClientConfig) {
    return createOpenAICompatible({ apiKey, baseURL, name: "deepseek" });
  }
}

const deepseek = new DeepSeekProvider();

const ai = new AIService();
ai.use(deepseek.model({ id: "deepseek-v4-flash", name: "DeepSeek V4 Flash" }));
base.use(ai);

See Provider & Model Registration.

Official Service Registration

import { AccountsService, googleAccountsProvider } from "@downcity/services";

base.use(new AccountsService({
  providers: [
    googleAccountsProvider(),
  ],
}));

Routing

import { serve } from "@hono/node-server";
serve({ fetch: base.router().fetch, port: 43127, hostname: "127.0.0.1" });

instruction aggregation

Federation can return a plain-text instruction document for the current instance:

const text = await base.instruction();

The text aggregates:

how to use the Federation itself
which services are currently mounted
env requirements declared by each module
extra usage notes contributed by services

To read the same document remotely from a trusted admin side, call:

GET /v1/base/instruction

This route is admin-only and returns text/plain.

Auth

Federation automatically validates user_token and admin_secret_key. Access current user via ctx.user.

Database

ctx.db["table_name"] provides CityTableApi. Supports SQLite and PostgreSQL.