​

Architecture Overview

SO1 is a distributed automation platform that combines AI agents, workflow automation, and a unified control plane.

​

High-Level Architecture

Figure 1 — SO1 Platform Architecture. The console provides the user-facing dashboard; requests flow through the Hono BFF control plane to agents, n8n workflows, and PostgreSQL. Redis backs the n8n job queue, and VERITAS supplies the curated prompt library.

Trace ID	Requirement	Rationale	Test Case
SO1-ARCH-001	Console shall communicate with the control plane API exclusively through the BFF layer	Centralises auth, rate-limiting, and audit logging	TC-SO1-ARCH-001
SO1-ARCH-002	All agent outputs shall be validated against defined JSON schemas before persistence	Ensures data integrity and traceability through FORGE gates	TC-SO1-ARCH-002
SO1-ARCH-003	VERITAS prompts shall be version-controlled and bidirectionally linked to agent executions	Enables reproducible outputs and prompt regression testing	TC-SO1-ARCH-003

​

Component Details

​

SO1 Console

Repository: so1-io/so1-console

​

SO1 Control Plane API

Repository: so1-io/so1-control-plane-api

​

SO1 Agents

Repository: so1-io/so1-agents 20 specialized AI agents organized into 7 domains:

​

Veritas

Repository: so1-io/veritas Curated prompt library with 255 prompts organized by domain and purpose.

​

n8n

Self-hosted workflow automation platform with 400+ integrations.

​

Data Flow

​

Workflow Execution

Figure 2 — Workflow Execution Flow. User requests originate in the console, are routed through the Hono API’s /execute endpoint, and dispatched to n8n. PostgreSQL records an audit trail, while n8n fans out to external integrations.

Trace ID	Requirement	Rationale	Test Case
SO1-WF-001	Every workflow execution shall be audit-logged in PostgreSQL with a correlation ID	Provides traceability and supports incident forensics	TC-SO1-WF-001
SO1-WF-002	Workflow dispatch shall be asynchronous with status polling via the API	Prevents UI blocking for long-running workflows	TC-SO1-WF-002

​

Agent Workflow

Figure 3 — Agent Workflow with VERITAS. Developers interact via OpenCode, which provides context to a specialised SO1 agent. The agent processes work and produces schema-validated output. All three stages maintain a bidirectional link with VERITAS for prompt lookup and contribution.

Trace ID	Requirement	Rationale	Test Case
SO1-AGT-001	Agent output shall conform to a registered JSON schema before acceptance	Prevents malformed outputs from propagating downstream	TC-SO1-AGT-001
SO1-AGT-002	VERITAS prompts consumed by an agent shall be pinned to a specific version	Guarantees reproducibility across runs	TC-SO1-AGT-002

​

Deployment Architecture

​

Railway Deployment

Figure 4 — Railway Deployment Topology. All production services run within a single Railway project. The Console, API, and n8n share a private network with PostgreSQL and Redis as managed data stores.

Trace ID	Requirement	Rationale	Test Case
SO1-DEP-001	All production services shall run in a single Railway project with private networking	Simplifies secrets management and reduces cross-network latency	TC-SO1-DEP-001
SO1-DEP-002	Database and cache services shall use managed Railway add-ons with automated backups	Reduces operational burden and improves disaster recovery posture	TC-SO1-DEP-002

​

CI/CD Pipeline

Figure 5 — CI/CD Pipeline. Pushes to GitHub trigger Actions workflows that build, test, and deploy to Railway. Slack notifications are dispatched in parallel with deployment.

Trace ID	Requirement	Rationale	Test Case
SO1-CICD-001	Every push to main shall trigger an automated build-test-deploy pipeline	Eliminates manual deployment steps and ensures consistent releases	TC-SO1-CICD-001
SO1-CICD-002	Pipeline failures shall notify the team via Slack within 60 seconds	Shortens incident detection time	TC-SO1-CICD-002

​

Security Architecture

​

Authentication Flow

Figure 6 — Authentication Flow. Users initiate OAuth login through the console. Better Auth manages session creation and delegates to GitHub OAuth. A session cookie is returned for subsequent requests.

Trace ID	Requirement	Rationale	Test Case
SO1-AUTH-001	Authentication shall use OAuth 2.0 via Better Auth with GitHub as the identity provider	Leverages existing GitHub identities and avoids custom credential management	TC-SO1-AUTH-001
SO1-AUTH-002	Sessions shall be stored as secure, HttpOnly cookies with configurable TTL	Mitigates XSS-based session theft	TC-SO1-AUTH-002

​

API Security

​

Monitoring & Observability

​

Related Documentation