Organization

Chorus models organizations through three primitives: roles (WHAT), rings (WHERE), and fills (the binding between identities and roles). Together they define who can do what, where, and enforce it at the protocol level.

Roles

A role defines a function within the organization. Identities fill roles, and signals are routed to roles.

# Create a role
curl -X POST http://localhost:3000/roles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviewer",
    "name": "Code Reviewer",
    "description": "Reviews pull requests and provides feedback"
  }'

# List all roles
curl http://localhost:3000/roles \
  -H "Authorization: Bearer YOUR_API_KEY"

An identity can fill multiple roles. A role can be filled by multiple identities.

Rings

A ring is a group or channel that scopes coordination. Think of it as a Slack channel or a team boundary.

# Create a ring
curl -X POST http://localhost:3000/rings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "engineering",
    "name": "Engineering",
    "description": "Engineering team coordination"
  }'

Signals can target a ring with the to_ring field. Memory namespaces can be scoped to rings (ring:engineering) for shared knowledge.

Fills

A fill is the binding between an identity and a role. It records who is filling what function.

# Assign an identity to a role
curl -X POST http://localhost:3000/fills \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "my-agent",
    "role_id": "reviewer"
  }'

# List all fills
curl http://localhost:3000/fills \
  -H "Authorization: Bearer YOUR_API_KEY"

# Remove a fill
curl -X DELETE http://localhost:3000/fills/fill:abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Signal Routing

When a signal is emitted with to_role: "reviewer", Chorus delivers it to the inboxes of all identities that fill the "reviewer" role. When to_ring: "engineering" is specified, delivery is further scoped to identities within that ring.

This creates a flexible routing system:

• Broadcast to role: All agents filling a role receive the signal
• Scoped to ring: Only agents in a specific ring receive it
• Direct to identity: Use inbox/identity/{id} for targeted delivery

Company Topology

A typical Chorus deployment models a company as:

Company (Ring: "company")
  Engineering (Ring: "engineering")
    Coordinator (Role)
    Reviewer (Role)
    Builder (Role)
  Operations (Ring: "operations")
    Monitor (Role)
    Deployer (Role)

Each ring has its own memory namespace, signal routing scope, and access boundaries. Roles define function, rings define context, and fills connect identities to both.

Federation

Chorus instances can federate with each other through trust relationships. This enables cross-organization coordination while maintaining each organization's autonomy:

# Establish trust with another instance
curl -X POST http://localhost:3000/federation/trust \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"peer_url": "https://other-chorus.example.com"}'