Design Overview¶

Core Vision¶

SynthOrg is a configurable AI company framework where AI agents operate within a virtual organisation. 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 optimisation, 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-specialised work-stream parallelism, organisational simulation fidelity, and audit-grade decision trails, not reasoning parallelism. See S1 Multi-Agent Architecture Decision for the full reconciliation.

Pre-alpha: heavy development, not yet usable

SynthOrg is in active pre-alpha development. The framework is not yet production-ready: expect bugs, rough edges, missing polish, and breaking changes between releases. Operator-facing onboarding (real provider, real workloads, dashboard polish) has not been exercised end to end. Use it for research and contribution, not for real workloads.

These pages describe the designed behaviour of SynthOrg and are the source of truth for that design. Protocol interfaces and pluggable strategies are designed upfront to inform architecture; individual subsystems may still have a gap between the spec and the code. Treat any such gap as the work, not the spec. For what is shipped now versus on the roadmap, 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 organisation 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.
Organisation & Templates

Company types, organisational 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 organisational 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, and 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 colour system, theme architecture, typography, density, and animation guidelines.