Skip to content
Mahoosuc OS Documentation

Architecture Overview

System Architecture

Mahoosuc OS follows a layered architecture with clear separation between the agent orchestration layer, product applications, and shared infrastructure.

┌─────────────────────────────────────────────────────────┐
│                    Claude Code Interface                 │
│              (slash commands + agent routing)            │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                    Agent Layer (.claude/)                │
│   45+ specialized agents │ 32 skills │ 120+ commands    │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                    Product Suite (products/)             │
│  SalesOS │ ContentStudio │ LinkedIn OS │ DevFlow │ ...  │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│              Shared Infrastructure                       │
│    PostgreSQL │ Redis │ Prometheus │ Grafana │ Loki     │
└─────────────────────────────────────────────────────────┘

Key Design Principles

  • Enhance, don’t remove — always add capabilities rather than strip existing ones
  • Spec-driven — every feature begins with a spec, not code
  • Human approval gates — all data-modifying operations require confirmation
  • Compound learning — engineering insights are captured and fed back into the system

Component Directories

DirectoryPurpose
.claude/agents/Agent definitions (markdown with frontmatter)
.claude/commands/120+ slash commands
.claude/skills/Preloadable skill modules
.claude/standards/Coding conventions and API contracts
products/Product applications
infrastructure/Observability, shared services
scripts/Automation and tooling