One page that explains how city, agent, session, service, plugin, and console actually relate to each other in Downcity

Project Logic Overview

The fastest way to understand Downcity is not to start from commands, but from responsibilities.

You can understand the whole system through 6 objects:

city runtime
console
agent
session
service
plugin

The Short Version

city owns global resources and global state
agent owns one project
session is where real execution happens
service owns the main flow
plugin owns extensions
console visualizes and controls all of the above

1. Four Scopes

You can think of the system in 4 scopes:

Scope	Responsibility	Typical data
`city`	global runtime, model pool, agent registry, global plugin lifecycle	`~/.downcity/downcity.db`, running agent registry
`agent project`	one project's execution config	`<project>/downcity.json`
`session`	one real chat or task execution	message history, prompt, compacted context
`execution`	the capability surface exposed during one run	`session`, `plugins`, `logger`, `config`

The most important boundary is:

whether a plugin is enabled belongs to city
how an agent uses that plugin belongs to the agent

For example:

whether asr is enabled is city-level state
which asr.modelId one agent uses is agent-level config

2. Where Config Lives

From a user perspective, you only need to remember two places.

Global directory

~/.downcity/
stores city-level runtime data
such as model pool, global env, channel accounts, plugin lifecycle, and running agent registry

Project directory

<project>/downcity.json
stores execution config for one agent project
such as execution binding, channel binding, and plugin parameters

That means:

for global state, look at Console or ~/.downcity
for project parameters, look at the project's downcity.json

3. Relationship Map

3.1 Key Directory Tree

This is not the full repo tree. It only keeps the directories that matter most when you are trying to understand the system.

Repository root

downcity/
├── homepage/                        # Website and user-facing docs
│   ├── app/                         # Docs site app
│   ├── content/docs/                # User docs content
│   └── public/                      # Static site assets
├── packages/
│   ├── downcity/                    # Core runtime, CLI, service, and plugin implementation
│   └── downcity-ui/                 # Shared UI component library
├── products/
│   ├── console/                     # Console frontend
│   ├── console-ui/                  # Older Console UI-related artifacts
│   └── chrome-extension/            # Browser extension
├── scripts/                         # Repo-level scripts
└── .agents/                         # Local skill and agent helper directory

Core runtime source

packages/downcity/src/
├── main/                            # Platform entrypoints and host orchestration
│   ├── city/                        # City runtime, global env, model pool, runtime paths
│   ├── agent/                       # Agent host, project loading, agent runtime assembly
│   ├── modules/                     # CLI, Console API, HTTP, and RPC entrypoints
│   ├── plugin/                      # Plugin registry, catalog, lifecycle, dispatch
│   └── service/                     # Service registry and shared service host logic
├── services/                        # Main-path service implementations
│   ├── chat/                        # Chat main flow, channel integration, message orchestration
│   ├── task/                        # Task main flow
│   ├── memory/                      # Memory main flow
│   └── shell/                       # Shell main flow
├── plugins/                         # Extension implementations
│   ├── auth/                        # Auth-related plugin
│   ├── skill/                       # Skill catalog and lookup/install
│   ├── web/                         # Web provider selection and prompt injection
│   ├── asr/                         # Speech recognition
│   ├── tts/                         # Text-to-speech
│   └── voice/                       # Legacy voice compatibility implementation
├── session/                         # Session execution, prompts, tools, context handling
├── shared/
│   ├── constants/                   # Shared constants
│   ├── types/                       # Global shared types
│   └── utils/                       # Shared utilities
└── services/                        # Concrete service implementations

Console frontend source

products/console/src/
├── app/                             # App entry
├── components/                      # Page components and dashboard modules
├── hooks/                           # Dashboard state and behavior hooks
├── lib/                             # API, routing, query, and mutation helpers
└── types/                           # Console frontend types

How To Read The Tree

if you want global model pool, global env, or global plugin lifecycle: start in main/city
if you want to understand how one project agent starts and reads downcity.json: start in main/agent
if you want to see where Console pages get data from: start in main/modules/console and products/console/src/lib
if you want the main flow for chat, task, memory, or shell: read services/*
if you want ASR, TTS, Web, or Skill capability code: read plugins/*
if you want prompt, tools, and real execution logic: read session/*

4. What Each Layer Does

`city runtime`

the global host of the whole system
manages the global database, runtime directories, and agent registry
decides which plugins are enabled at the city level
powers the Console control plane

You can think of it as the platform layer of Downcity.

`console`

the UI and API control plane for city
shows agents, model pool, channel accounts, and plugin state
Global > Plugins shows city-level plugin state
it does not represent one specific agent's local parameters

`agent`

one project maps to one agent
loads project config
owns the session store
wires services and plugins into the unified execution environment

An agent is a project host, not one execution turn.

`session`

the place where model execution actually happens
one chat conversation is a session
one task run is also a session
prompt assembly, messages, context compaction, and reply generation all happen around the session

So: