Project Logic Overview

Downcity is easiest to understand from the product problem first: AI builders should not rebuild the same agent backend for every product, workflow, or customer demo.

The core relationship is:

• product surfaces own the user experience
• agents execute work inside explicit runtime boundaries
• Downcity runtime services own repeated infrastructure such as models, env, auth, service routing, usage, balance, and payment
• Console, Chrome Extension, SDKs, and UI components expose that runtime to builders and teams

Runtime nouns

• downcity: the overall runtime and CLI surface
• console: global control plane
• agent: one project runtime
• session: one execution thread
• plugin: one capability boundary
• city: the current package/runtime name for City infrastructure

The shortest model

• products create the experience
• agents run the work
• sessions execute turns
• plugins expose capabilities
• City keeps repeated backend concerns out of every product

Plugin families

Local plugins

• attached directly to one SDK Agent
• usually action-first or hook-oriented

Managed plugins

• owned by one target agent runtime
• may hold lifecycle-owned runtime state

Why this matters

When reading current code or docs, start with the product boundary:

• if you need product operation, look at downcity, console, and product docs
• if you need execution ownership, look at agent and session
• if you need capability ownership, look at plugin
• if you need shared backend ownership, look at the City SDK and services docs