Design Overview¶

Core Vision¶

SynthOrg is a configurable AI company framework where AI agents operate within a virtual organization. Each agent has a defined role, personality, skills, memory, and model backend. The company can be configured from a 2-person startup to a 50+ enterprise, handling software development, business operations, creative work, or any domain.

Design Principles¶

Configuration over Code

Company structures, roles, and workflows are defined via config, not hardcoded.
Provider Agnostic

Any LLM backend: cloud APIs, OpenRouter, Ollama, custom endpoints.
Composable

Mix and match roles, teams, and workflows. Build any type of company.
Observable

Every agent action, communication, and decision is logged and visible.
Autonomy Spectrum

From full human oversight to fully autonomous operation.
Cost Aware

Built-in budget tracking, model routing optimization, and spending controls.
Extensible

Plugin architecture for new roles, tools, providers, and workflows.
Local First

Runs locally with the option to expose on network or host remotely later.

What This Is NOT¶

Not a chatbot or conversational AI product
Not locked to software development only (though that is a primary use case)
Not a wrapper around a single model or provider
Not a toy/demo: designed for real, production-quality output
Not a reasoning parallelizer. Single-agent reasoning is typically more token-efficient on isolated multi-hop questions, and SynthOrg's auto topology selector defaults to single-agent for such tasks. SynthOrg's value is role-specialized work-stream parallelism, organizational simulation fidelity, and audit-grade decision trails, not reasoning parallelism. See S1 Multi-Agent Architecture Decision for the full reconciliation.

How to read the design specification (important)

These pages describe the designed behaviour of SynthOrg and are the source of truth for that design. They are documented upfront to inform architecture; protocol interfaces are designed even where the behaviour is not yet wired. Be specific about current state: the autonomous agent runtime that makes the organisation execute work is in active development and not yet wired (AgentEngine is not constructed in the shipped path), so subsystems that depend on a running agent (coordination, coordination metrics, intake, approval enforcement, self-improvement, and the agent execution loop itself) are designed and unit-tested as components but not exercised end to end. Treat any gap between a spec and the code as the work, not the spec. For exactly what is available now versus in active development, see the Roadmap.

Configuration Philosophy¶

The framework follows progressive disclosure: users only configure what they need.

Templates handle 90% of users: pick a template, override 2-3 values, go
Minimal config for custom setups: everything has sensible defaults
Full config for power users: every knob exposed but none required

Minimal custom company (all other settings use defaults):

company:
  name: "Acme Corp"
  template: "startup"
  budget_monthly: 50.00

All configuration systems in the framework are pluggable: strategies, backends, and policies are swappable via protocol interfaces without modifying existing code. Sensible defaults are chosen for each, documented in the relevant section alongside the full configuration reference.

Glossary¶

Term	Definition
Agent	An AI entity with a role, personality, model backend, memory, and tool access. The primary entity in the framework. Within a company context, agents serve as the company's employees.
Company	A configured organization of agents with structure, hierarchy, and workflows
Department	A grouping of related roles (Engineering, Product, Design, Operations, etc.)
Role	A job definition with required skills, responsibilities, authority level, and tool access
Skill	A capability an agent possesses (coding, writing, analysis, design, etc.)
Task	A unit of work assigned to one or more agents
Project	A collection of related tasks with a goal, deadline, and assigned team
Meeting	A structured multi-agent interaction for decisions, reviews, or planning
Artifact	Any output produced by agents: code, documents, designs, reports, etc.

Entity Relationships¶

The following diagram illustrates how the core entities in SynthOrg relate to each other:

Agents / HR & Agent Lifecycle

Agent identity (personality, skills, identity versioning) plus the full HR lifecycle: seniority, role catalog, hiring, firing, performance tracking, evaluation, promotions, and evolution.
Organization & Templates

Company types, organizational hierarchy, department configuration, template system, and dynamic scaling.
Communication

Message bus, delegation, conflict resolution, and meeting protocols.
Engine

Execution loops, task decomposition, routing, orchestration, and recovery.
Memory

Agent memory, retrieval pipeline, shared organizational memory, and consolidation.
Semantic Ontology

Shared entity vocabulary, versioned definitions, drift detection, and context injection for inter-agent semantic alignment.
Providers / Budget / Tools / Security

LLM provider abstraction, budget enforcement, tool sandboxing, progressive trust, autonomy levels, and approval workflows.
Observability / Notifications / Backup / Deployment

Structured logging, correlation tracking, operator alerts, backup and restore, container runtime.
Integrations

External service connection catalog, OAuth 2.1, webhooks, health checks, rate limiting, MCP catalog, and tunnel.
Persistence

Repository protocol abstraction, SQLite and Postgres backends, append-only time-series tables, TimescaleDB hypertables, and extension strategy.
Brand Identity & UX

Visual identity, semantic color system, theme architecture, typography, density, and animation guidelines.