Skip to main content

Architecture Overview

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

High-Level Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                           SO1 PLATFORM                                   │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌────────────────────────────────────────────────────────────────┐    │
│   │                      SO1 CONSOLE (Next.js)                     │    │
│   │              Dashboard • Workflows • Settings                   │    │
│   └───────────────────────────┬────────────────────────────────────┘    │
│                               │                                          │
│                               ▼                                          │
│   ┌────────────────────────────────────────────────────────────────┐    │
│   │                 SO1 CONTROL PLANE API (Hono)                   │    │
│   │     BFF Layer: Auth • Workflows • Integrations • Webhooks      │    │
│   └───────────────────────────┬────────────────────────────────────┘    │
│                               │                                          │
│         ┌─────────────────────┼─────────────────────┐                   │
│         │                     │                     │                   │
│         ▼                     ▼                     ▼                   │
│   ┌──────────┐         ┌──────────┐         ┌──────────┐               │
│   │ SO1-AGENTS│        │   n8n    │         │ PostgreSQL│               │
│   │ (OpenCode)│        │ Workflows│         │  Database │               │
│   └──────────┘         └──────────┘         └──────────┘               │
│         │                     │                     │                   │
│         │              ┌──────┴──────┐              │                   │
│         │              │   Redis     │              │                   │
│         │              │   Queue     │              │                   │
│         │              └─────────────┘              │                   │
│         │                                           │                   │
│         ▼                                           │                   │
│   ┌──────────┐                                      │                   │
│   │ VERITAS  │◄─────────────────────────────────────┘                   │
│   │ Prompts  │                                                          │
│   └──────────┘                                                          │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Component Details

SO1 Console

Repository: so1-io/so1-console
TechnologyVersionPurpose
Next.js16React framework with App Router
React19UI components
TanStack Query5Data fetching and caching
Tailwind CSS4Styling
TypeScript5.7Type safety

SO1 Control Plane API

Repository: so1-io/so1-control-plane-api
TechnologyVersionPurpose
Hono4Web framework
Drizzle ORM-Database queries
Zod3Schema validation
Better Auth-Authentication
TypeScript5.7Type safety

SO1 Agents

Repository: so1-io/so1-agents 20 specialized AI agents organized into 7 domains:
DomainAgentsPrimary Output
Orchestration2Task coordination
Automation3n8n workflows
Engineering3TypeScript code
DevOps3CI/CD configs
Documentation3MDX/OpenAPI
Prompts3Veritas drafts
Incident3Response plans

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

User Request


┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Console   │───►│  API (Hono) │───►│    n8n      │
│  (Next.js)  │    │   /execute  │    │  Workflow   │
└─────────────┘    └─────────────┘    └─────────────┘
                          │                  │
                          ▼                  ▼
                   ┌─────────────┐    ┌─────────────┐
                   │  PostgreSQL │    │  External   │
                   │   (audit)   │    │  Services   │
                   └─────────────┘    └─────────────┘

Agent Workflow

Developer Prompt


┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   OpenCode   │───►│  SO1 Agent   │───►│   Output     │
│  (context)   │    │  (process)   │    │  (schema)    │
└──────────────┘    └──────────────┘    └──────────────┘
       │                   │                   │
       │                   ▼                   │
       │            ┌──────────────┐           │
       └───────────►│   Veritas    │◄──────────┘
                    │  (prompts)   │
                    └──────────────┘

Deployment Architecture

Railway Deployment

┌─────────────────────────────────────────────────────────────┐
│                     RAILWAY PROJECT                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Production Environment                                    │
│   ┌───────────┐  ┌───────────┐  ┌───────────┐             │
│   │  Console  │  │    API    │  │    n8n    │             │
│   │  (Next)   │  │  (Hono)   │  │           │             │
│   └───────────┘  └───────────┘  └───────────┘             │
│         │              │              │                    │
│         └──────────────┼──────────────┘                    │
│                        │                                    │
│   ┌───────────┐  ┌───────────┐                             │
│   │ PostgreSQL│  │   Redis   │                             │
│   └───────────┘  └───────────┘                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

CI/CD Pipeline

GitHub Push


┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   GitHub    │───►│   Build &   │───►│   Deploy    │
│   Actions   │    │    Test     │    │  (Railway)  │
└─────────────┘    └─────────────┘    └─────────────┘


                   ┌─────────────┐
                   │   Notify    │
                   │   (Slack)   │
                   └─────────────┘

Security Architecture

Authentication Flow

User Login


┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Console   │───►│ Better Auth │───►│   GitHub    │
│  (OAuth)    │    │  (Session)  │    │   OAuth     │
└─────────────┘    └─────────────┘    └─────────────┘


                   ┌─────────────┐
                   │   Session   │
                   │   Cookie    │
                   └─────────────┘

API Security

LayerProtection
TransportHTTPS/TLS 1.3
AuthenticationBetter Auth + Sessions
AuthorizationRBAC (org/project/user)
ValidationZod schemas
Rate LimitingPer-org throttling

Monitoring & Observability

ComponentToolPurpose
MetricsRailway MetricsCPU, Memory, Network
LogsRailway LogsApplication logging
ErrorsSentryError tracking
UptimeExternal checksAvailability monitoring