Skip to main content

​
System Architecture

Welcome to the OpsHub Architecture documentation. This section provides comprehensive information about OpsHub’s system design, architecture decisions, and technical implementation.

​
Overview

OpsHub is built on a modern, cloud-native architecture designed for scalability, reliability, and maintainability. The system follows microservices principles with clear separation of concerns and domain-driven design.

​
Architecture Principles

​
Cloud-Native Design

  • Containerized services - All components run in Docker containers
  • Horizontal scaling - Services scale independently based on load
  • Resilient - Built to handle failures gracefully
  • Observable - Comprehensive monitoring and logging

​
Domain-Driven Design

  • Bounded contexts - Clear boundaries between business domains
  • Multi-schema database - Domain isolation at the data layer
  • Event-driven - Asynchronous communication between services
  • CQRS patterns - Separation of read and write models

​
Modern Stack

  • Next.js 15 - Server-side rendering and static generation
  • FastAPI - High-performance Python backend
  • PostgreSQL - Relational database via Supabase
  • Temporal - Durable workflow orchestration
  • Redis - Caching and pub/sub

​
System Components

​
Frontend Layer

  • Next.js Application - React-based UI with SSR
  • Component Library - Reusable UI components
  • State Management - Zustand for client state
  • Real-time Updates - WebSocket connections

​
API Gateway

  • FastAPI Services - RESTful API endpoints
  • Authentication - JWT-based auth with Supabase
  • Rate Limiting - Request throttling and quotas
  • API Versioning - Backward compatibility

​
Business Logic Layer

  • Domain Services - Core business logic
  • AI Agent System - LangGraph-based agents
  • Workflow Engine - Temporal workflows
  • Validation Framework - Business rule validation

​
Data Layer

  • PostgreSQL - Primary data store
  • Multi-schema Design - Domain separation
  • Row-Level Security - Data isolation
  • Redis Cache - Performance optimization

​
Integration Layer

  • External APIs - Third-party integrations
  • Data Import/Export - ETL pipelines
  • Webhook System - Event notifications
  • Message Queue - Asynchronous processing

System Architecture

Overall system architecture and components

Agent Architecture

AI agent system architecture and design

Dashboard Architecture

Dashboard and analytics architecture

API Architecture

Backend API design and patterns

​
Architecture Documentation

​
System Architecture

  • Overall Architecture - Complete system design
  • Current Situation - Current state and roadmap
  • Beta Limitations - Known limitations

​
Agent System Architecture

  • Agent Framework Decision - ADR for agent framework
  • Agent Framework V2 - Updated agent design
  • Agent Intelligence Framework - AI agent architecture
  • Agent UI Control - UI integration patterns
  • Agent UI Updates - Real-time update flow
  • Integration Patterns - Agent integration approaches
  • Spreadsheet Integration - Excel integration
  • Presentation Integration - PowerPoint integration
  • SQL Execution - Database query execution

​
Specialized Architecture

  • Dashboard Architecture - Visualization system
  • Analytics Architecture - Data mart design
  • API Backend - Backend API structure
  • Claude Integration - AI model integration
  • Claude UI - Claude UI patterns

​
Key Architectural Patterns

​
Microservices

  • Independent services with clear boundaries
  • API-first design
  • Service discovery
  • Load balancing

​
Event-Driven Architecture

  • Domain events for state changes
  • Event sourcing for audit trails
  • Pub/sub for real-time updates
  • CQRS for read/write separation

​
Multi-Tenancy

  • Organization-based isolation
  • Row-level security
  • Tenant-aware services
  • Shared infrastructure

​
Security Architecture

  • Defense in depth
  • Zero trust principles
  • Encryption at rest and in transit
  • Role-based access control

​
Technology Stack

​
Frontend

  • Framework: Next.js 15.0.3
  • UI Library: React 18.2.0
  • Language: TypeScript 5.x
  • Styling: Tailwind CSS 3.4.14
  • State: Zustand 5.0.8

​
Backend

  • API: FastAPI (Python 3.13+)
  • Workflows: Temporal 1.13.1
  • AI: LangGraph with OpenAI/Anthropic
  • ORM: SQLAlchemy

​
Infrastructure

  • Database: PostgreSQL 15+ (Supabase)
  • Cache: Redis
  • Storage: S3-compatible object storage
  • CDN: Vercel Edge Network
  • Hosting: Vercel (frontend), Fly.io (backend)

​
Performance & Scalability

​
Performance Targets

  • API Response: < 200ms (p95)
  • Page Load: < 1s (p95)
  • Dashboard Refresh: < 500ms
  • Concurrent Users: 10,000+

​
Scaling Strategy

  • Horizontal scaling for API services
  • Auto-scaling based on load
  • Database connection pooling
  • CDN for static assets
  • Redis caching for hot data

​
Deployment

​
Environments

  • Development - Local development
  • Staging - Pre-production testing
  • Production - Live environment

​
CI/CD Pipeline

  • GitHub Actions for automation
  • Vercel for frontend deployments
  • Fly.io for backend deployments
  • Automated testing before deployment

​
Getting Started

  1. System Architecture - Start with overall architecture
  2. Agent Framework - Understand AI agent design
  3. Dashboard Architecture - Explore visualization system
  4. Developer Guide - Set up development environment
Use the sidebar to explore:
  • Architecture Overview - System design and component architecture
  • Agent Architecture - AI agent system detailed design
  • System Design - Claude integration and current state
For implementation details and setup instructions, see the Developer Docs section.