Skip to main content

Architecture Documentation, Workspaces, and Pattern Extraction

Architecture Documentation, Workspaces, and Pattern Extraction

Complete Architecture Documentation (2026-02-05)

141 KB total documentation covering GitLab organization structure (82 active projects, 11 subgroups), multi-workstation architecture, visual structure diagrams, development workflow, and architecture decisions.

GitLab Organization (82 Active Projects)

  • Agent Platform Core: 15 projects (agent-mesh, agent-protocol, agent-router, agent-brain, agent-buildkit, MCP servers, orchestration)
  • Infrastructure: 12 projects (docker-configs, k8s-manifests, compliance-engine, workflow-engine, monitoring)
  • Drupal: 18 projects (ai_agents_ossa, api_normalization, LLM modules, themes, recipes)
  • Platform Agents: 50+ packages (@bluefly/15, @drupal/8, @gitlab/6, @k8s/5, @mcp/4, @ossa/1)
  • Tools: 10 projects, Security: 5 projects, Data: 8 projects, CI/CD: 4 projects

3 Proposed Subgroups

  • Tooling: buildkit, cli-tools, dev-tools
  • Frameworks: api-normalization, compliance-engine, workflow-engine
  • OSSA: All OSSA packages (currently scattered)

Multi-Workstation Architecture (4 Environments)

  1. Mac M4 (primary dev, M4 Max 128GB)
  2. Mac M3 (secondary dev, M3 Max 96GB, iCloud sync for handoff)
  3. GitLab Workspaces (cloud agent execution, isolated environments)
  4. NAS BlueFlyNAS (services, data, production, 32GB RAM, 24TB)

Architecture Decision Records

  • ADR-001: GitLab-First Workflow (approved 2026-01-28)
  • ADR-002: iCloud Worktree Strategy (approved 2026-02-01)
  • ADR-003: NAS Role Separation - services/data only, no development (approved 2026-02-01)

Multi-Workstation + GitLab Workspaces Architecture (2026-02-05)

3-layer architecture:

  • Layer 1: Development Workstations (M4/M3 for human work, buildkit/agent-studio/Drupal UI)
  • Layer 2: GitLab (source of truth + agent execution via GitLab Workspaces)
  • Layer 3: NAS Infrastructure (Docker services, databases, storage, production apps)

Key distinction: Development happens on M4/M3, agents execute in GitLab Workspaces, services run on NAS.

Pattern Extraction (2026-02-06)

Extracted useful patterns from Claude desktop sessions into EXISTING packages (zero new packages created). 5 phases executed in parallel, 30 minutes.

Patterns Added

  1. ValidationResult Utility -> compliance-engine (85 lines): ValidationError interface, ValidationResult<T>, factory functions, merge utility
  2. File Discovery -> agent-brain (105 lines): Recursive file discovery with filtering, language extension mapping, symlink deduplication
  3. Plugin Manifest Schema -> agent-protocol (90 lines): Zod schema for plugin.json, MCP server config, validation functions
  4. Config Loading -> agent-router, agent-mesh, agent-protocol, agent-brain (4 files): Standardized Zod-validated config pattern across all packages
  5. Documentation Templates -> technical-docs (4 files): Package README, skill, agent manifest templates

Total: 7 new files across 5 packages, ~400 lines of reusable utility code, 274 lines of documentation templates.