Appearance

Platform Architecture ​

Overview of the Zeron platform architecture and service integration.

High-Level Architecture ​

┌─────────────────────────────────────────────────────────────┐
│                     Zeron Platform                           │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
┌──────────────────┐  ┌──────────────┐  ┌──────────────────┐
│   Conductor      │  │   Feedback   │  │    Dashboard     │
│   (TypeScript)   │  │   Service    │  │   (Python)       │
│                  │  │  (TypeScript)│  │                  │
│  - Jira Polling  │  │  - Multi-    │  │  - Analytics     │
│  - Agent Spawn   │  │    tenant    │  │  - Visualization │
│  - Validation    │  │  - AI Chat   │  │  - Monitoring    │
│  - Metrics       │  │  - Widgets   │  │                  │
└──────────────────┘  └──────────────┘  └──────────────────┘
          │                   │                   │
          └───────────────────┼───────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
┌──────────────────┐  ┌──────────────┐  ┌──────────────────┐
│      Redis       │  │  PostgreSQL  │  │      Neo4j       │
│   (State/Cache)  │  │  (Relational)│  │     (Graph)      │
└──────────────────┘  └──────────────┘  └──────────────────┘

Service Breakdown ​

Conductor Service ​

Purpose: AI-Native Development Orchestrator

Key Components:

  • Multi-Project Conductor (src/multi-project-conductor.ts)
  • Agent Manager (CLI & SDK modes)
  • Redis State Management
  • Jira Integration
  • Budget Tracking
  • Worker Pool (parallel processing)

Data Flow:

  1. Poll Jira for "Ready for Dev" tickets
  2. Build context (ticket + learnings + checklist)
  3. Spawn builder agent (Claude Code)
  4. Validate implementation
  5. Spawn reality validator
  6. Update Jira with results
  7. Capture learnings

Feedback Service ​

Purpose: Multi-tenant feedback management with AI conversations

Key Components:

  • API Backend (packages/api/)
  • Frontend Client (packages/feedback-client/)
  • Prisma ORM
  • LLM Router Bridge
  • Widget System

Data Flow:

  1. Widget embedded in client site
  2. User submits feedback
  3. Stored in PostgreSQL
  4. AI conversation initiated
  5. LLM routing (Anthropic/OpenAI)
  6. Semantic search with pgvector
  7. Analytics and reporting

Dashboard ​

Purpose: Business intelligence and visualization

Key Components:

  • Streamlit App (dashboard/app.py)
  • Components (dashboard/components/)
  • Utils (dashboard/utils/)

Data Sources:

  • Neo4j: Graph data
  • PostgreSQL: Feedback data
  • Redis: Real-time metrics
  • Conductor: Development metrics

Data Layer ​

Neo4j (Graph Database) ​

Use Cases:

  • Knowledge graph representation
  • Entity relationships
  • Discovery engine data

Configuration:

  • Port: 7474 (HTTP), 7687 (Bolt)
  • Docker containerized
  • APOC plugins enabled

PostgreSQL (Relational) ​

Use Cases:

  • Feedback service data
  • User/project management
  • Embeddings (pgvector)

Features:

  • Prisma ORM
  • Vector similarity search
  • Multi-tenant isolation

Redis (In-Memory) ​

Use Cases:

  • Conductor state management
  • Job queues
  • Caching layer
  • Session storage

Persistence:

  • AOF (append-only file)
  • RDB snapshots
  • Hourly backups

AI/LLM Layer ​

Claude Agent SDK ​

Purpose: Headless agent spawning for Conductor

Flow:

  1. Conductor builds agent context
  2. SDK spawns Claude Code instance
  3. Agent executes development work
  4. Returns manifest/results
  5. Fresh validator instance tests

LLM Router ​

Purpose: Unified AI provider interface

Providers:

  • Anthropic Claude (primary)
  • OpenAI GPT (alternative)

Features:

  • Prompt caching
  • Token optimization
  • Cost tracking
  • Fallback handling

Integration Points ​

Conductor ↔ Jira ​

Integration: REST API + custom fields

Data Exchange:

  • Poll tickets: GET /rest/api/3/search
  • Update status: POST /rest/api/3/issue/{id}/transitions
  • Store manifest: customfield_10051
  • Store validation: customfield_10050

Feedback Service ↔ OrderDay ​

Integration: Cross-origin widget embedding

Data Exchange:

  • Widget JavaScript bundle
  • CORS-optimized API
  • Real-time feedback submission
  • AI conversation responses

Conductor ↔ GitHub ​

Integration: gh CLI

Operations:

  • PR creation
  • PR status checks
  • Branch management
  • Commit history analysis

Security Architecture ​

Authentication ​

  • JWT tokens (feedback service)
  • API keys (external integrations)
  • Environment variables (secrets)

Multi-Tenancy ​

  • Organization-level isolation
  • Project-level isolation
  • Row-level security (PostgreSQL)

CORS ​

  • Configured per service
  • Widget-specific allowlists
  • Credential handling

Deployment Architecture ​

Production Services ​

Vercel (Edge Network)
├── Feedback Service API
├── Feedback Client
└── Public Website

Self-Hosted
├── Conductor
├── Dashboard
├── Neo4j (Docker)
└── Redis

Infrastructure ​

  • Docker Compose: Local development
  • Vercel: Production web services
  • GitHub Actions: CI/CD (future)

Monorepo Structure ​

zeron/
├── conductor/          # Development orchestration
├── feedback-service/   # Feedback management
├── dashboard/          # BI interface
├── public-website/     # Marketing site
├── learning-service/   # AI learning
├── discovery-engine/   # Data collection
├── nexus/              # Knowledge graph
├── prisma/             # Shared schema
└── scripts/            # Automation

Scalability Considerations ​

Conductor ​

  • Worker pools for parallel processing
  • Git worktrees for isolation
  • Redis for distributed state

Feedback Service ​

  • Multi-tenant PostgreSQL
  • Connection pooling
  • Serverless functions (Vercel)

Dashboard ​

  • Streamlit caching
  • Lazy data loading
  • Pre-computed metrics

Monitoring & Observability ​

Conductor Dashboard ​

  • Real-time ticket status
  • Cost tracking
  • Lean metrics
  • Activity logs

Logging ​

  • Winston (structured logging)
  • Service-specific log files
  • Error tracking

Metrics ​

  • Cycle time
  • Lead time
  • First-pass success rate
  • Cost per ticket
  • WIP tracking

Future Architecture Considerations ​

  • [ ] Central API Gateway
  • [ ] Event-driven architecture (message bus)
  • [ ] Microservice authentication (OAuth2)
  • [ ] Distributed tracing
  • [ ] Centralized logging (ELK stack)
  • [ ] Container orchestration (Kubernetes)

Part of the Zeron Platform | Built with VitePress

Copyright © 2025 Zeron