ARCH-001: SEA™ Container Architecture (C4 Model)

Type

Architecture Diagram Reference / System Design Specification

Status

Historical Reference - Original SEA™ Architecture

Purpose

Documents the container-level architecture of the original Sentient Enterprise Architecture (SEA™) 5.0 system using the C4 model. This represents the microservices architecture that informed the evolution to SEA-Forge™.

Context

This architecture represents the original SEA™ implementation with 13 microservices organized around the 4 core pillars. While SEA-Forge™ evolves this design, understanding the original container structure is essential for:

• Migration planning from SEA™ to SEA-Forge™
• Understanding service boundaries and responsibilities
• Identifying integration patterns and dependencies
• Informing bounded context definitions in SEA-Forge™

Container Overview

External Interfaces

User → Web Application → API Gateway → Internal Services

Total Container Count

• 1 Web Application (Frontend)
• 1 API Gateway
• 11 Backend Microservices

Container Catalog

1. Web Application

Technology: React/Next.js
Type: User Interface
Responsibility: Provides user interface for interacting with SEA™ services, including cognitive artifacts and documentation.

Interactions:

• Receives user input via HTTPS
• Makes API calls to API Gateway (HTTPS)
• Displays rendered documentation from CADSL Runtime

Notes:

• ⚠️ SEA-Forge™ has adopted Remix over Next.js (see ADR-002)
• This represents the original SEA™ frontend architecture

2. API Gateway

Technology: Kong Gateway
Type: Infrastructure / Gateway Pattern
Responsibility: Routes requests, enforces policies, and handles authentication/authorization.

Interactions:

• Receives all external requests from Web App
• Routes to internal services via Internal API
• Enforces cross-cutting concerns (auth, rate limiting, logging)

Downstream Services:

• Semantic Core Service
• Knowledge Graph Service
• CALM CLI Service
• Context Analyzer Service
• Recommendation Algorithm Service
• Artifact Engine Service
• CADSL Runtime & Renderer
• AI Agent Configuration Service
• User Feedback Processor
• Documentation Orchestrator

Core Pillar Services

3. Semantic Core & DSL Management Service

Bounded Context: Semantic Domain Management
Technology: Python/FastAPI
Pillar: Semantic Core (Policy + DSL)

Responsibility: Manages policies, DSL definitions, and semantic consistency.

Interactions:

• Updates/Queries → Knowledge Graph Service (Oxigraph Driver)
• Queried by → Project Context Analyzer

Key Capabilities:

• Policy storage and validation
• DSL definition management
• Semantic consistency enforcement
• Business vocabulary governance

4. Knowledge Graph Service

Bounded Context: Knowledge Graph Domain
Technology: Python/FastAPI
Pillar: Semantic Core (Data Layer)

Responsibility: Manages the Oxigraph Knowledge Graph, providing semantic context.

Interactions:

• Receives updates from → Semantic Core Service
• Integrates with → External Systems (API/Data Feeds)
• Queried by → Context Analyzer Service

Key Capabilities:

• Oxigraph graph database management
• Semantic relationship traversal
• Domain concept linking
• External system integration

5. CALM CLI Service

Bounded Context: Architectural Governance
Technology: Go/CLI
Pillar: Architectural Governance (CALM Integration)

Responsibility: Provides command-line interface for architectural governance and CALM validation.

Interactions:

• Queried by → Project Context Analyzer
• Called by → API Gateway

Key Capabilities:

• CALM specification validation
• Architectural pattern enforcement
• Design rule checking
• Version control for architecture

Technology Note:

• Uses Go for performance-critical architectural analysis
• CLI-first design for developer workflows

Cognitive Extension Services (Pillar 3)

6. Context Analyzer Service

Bounded Context: Cognitive Extension - Context Analysis
Technology: Python/FastAPI
Pillar: Cognitive Extension

Responsibility: Analyzes user input and system context to provide relevant information.

Interactions:

• Queries → Knowledge Graph Service (Oxigraph Driver)
• Queries → AI Agent Config Service (Internal API)
• Queried by → Artifact Engine Service

Key Capabilities:

• User intent analysis
• System state assessment
• Context extraction from knowledge graph
• Recommendation input preparation

7. Recommendation Algorithm Service

Bounded Context: Cognitive Extension - Recommendations
Technology: Python/FastAPI
Pillar: Cognitive Extension

Responsibility: Generates recommendations for cognitive artifacts and AI agent actions.

Interactions:

• Queried by → Artifact Engine Service
• Receives feedback from → User Feedback Processor (Message Queue)

Key Capabilities:

• Artifact type recommendation
• AI agent action suggestions
• Contextual relevance scoring
• Learning from user feedback

Integration Pattern:

• Asynchronous feedback loop via Message Queue

8. Artifact Engine Service

Bounded Context: Cognitive Extension - Artifact Generation
Technology: Python/FastAPI
Pillar: Cognitive Extension (CADSL)

Responsibility: Generates CADSL-based cognitive artifacts.

Interactions:

• Queries → Context Analyzer Service
• Queries → Recommendation Algorithm Service
• Provides CADSL to → CADSL Runtime & Renderer
• Queried by → Documentation Orchestrator

Key Capabilities:

• CADSL specification generation
• Artifact templating (checklists, maps, timelines, plans)
• Context-aware artifact customization
• Documentation artifact creation

9. CADSL Runtime & Renderer

Bounded Context: Cognitive Extension - Presentation
Technology: TypeScript/Node.js
Pillar: Cognitive Extension

Responsibility: Parses and renders CADSL artifacts into interactive UI components.

Interactions:

• Receives CADSL from → Artifact Engine Service
• Receives documentation CADSL from → Documentation Orchestrator
• Renders to → Web App (HTTPS)

Key Capabilities:

• CADSL parsing
• Interactive UI component generation
• Real-time artifact rendering
• Frontend integration

Technology Note:

• TypeScript/Node.js for type safety and frontend compatibility

10. AI Agent Configuration Service

Bounded Context: AI/Agent Management
Technology: Python/FastAPI
Pillar: Supporting Infrastructure

Responsibility: Manages Prompt Management DSL and AI agent configurations.

Interactions:

• Queried by → Context Analyzer Service

Key Capabilities:

• Prompt template management
• AI agent behavior configuration
• DSL for prompt engineering
• Agent persona definitions

11. User Feedback Processor

Bounded Context: Collaboration / User Feedback
Technology: Python/FastAPI
Pillar: Supporting Infrastructure

Responsibility: Collects and processes user interaction data and explicit feedback.

Interactions:

• Feeds data to → Recommendation Algorithm Service (Message Queue)

Key Capabilities:

• User interaction tracking
• Explicit feedback collection
• Behavioral analytics
• Feedback loop to recommendations

Integration Pattern:

• Asynchronous messaging for decoupled feedback processing

Documentation Generation Services (Pillar 4)

12. Documentation Orchestrator Service

Bounded Context: Documentation Generation - Orchestration
Technology: Python/FastAPI
Pillar: Automated Documentation (ADG Framework)

Responsibility: Coordinates automated documentation generation.

Interactions:

• Requests context from → Project Context Analyzer
• Requests documentation CADSL from → Artifact Engine Service
• Provides CADSL to → CADSL Runtime & Renderer

Key Capabilities:

• Documentation workflow orchestration
• Multi-source content aggregation
• Template selection and application
• Output format coordination

13. Project Context Analyzer

Bounded Context: Documentation Generation - Analysis
Technology: Python/FastAPI
Pillar: Automated Documentation

Responsibility: Extracts project context from codebase and specifications for documentation.

Interactions:

• Queries → Semantic Core Service
• Queries → CALM CLI Service
• Provides context to → Documentation Orchestrator

Key Capabilities:

• Codebase analysis
• Specification extraction
• Domain model discovery
• Architecture pattern detection

Integration Patterns

Synchronous Communication

Pattern: RESTful Internal APIs
Technology: HTTP/JSON

Used Between:

• API Gateway ↔ All Services
• Service-to-Service queries (Context Analyzer → Knowledge Graph)

Asynchronous Communication

Pattern: Message Queue
Technology: Not specified in diagram (likely RabbitMQ, Kafka, or Redis Streams)

Used Between:

• User Feedback Processor → Recommendation Algorithm Service

Benefits:

• Decoupled feedback processing
• Resilience to service failures
• Scalable event processing

Data Access Patterns

Oxigraph Driver (Direct):

• Semantic Core Service → Knowledge Graph Service
• Context Analyzer Service → Knowledge Graph Service

Internal API Calls:

• All other service-to-service communication

Technology Stack Summary

Backend Languages

• Python/FastAPI: 9 services (majority)
• Go: 1 service (CALM CLI - performance-critical)
• TypeScript/Node.js: 1 service (CADSL Runtime - frontend integration)

Frontend

• React/Next.js (Original SEA™ 5.0)
• ⚠️ Remix (SEA-Forge™ - see ADR-002)

Infrastructure

• Kong Gateway: API Gateway
• Oxigraph: Knowledge Graph database
• PostgreSQL: Relational data (implied, not shown in diagram)
• Message Queue: Asynchronous communication (technology TBD)

Architectural Patterns

Microservices Architecture

• Service per bounded context
• API Gateway pattern for external access
• Internal API mesh for service communication

Domain-Driven Design

• Services aligned with bounded contexts
• Clear service boundaries
• Upstream/downstream relationships

Event-Driven Architecture (Partial)

• Message queue for feedback processing
• Potential for broader event-driven patterns

Hexagonal Architecture (Implied)

• Services designed for external integration
• Anti-corruption layers at service boundaries

Service Dependencies Map

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
User
  ↓
Web App (React/Next.js)
  ↓
API Gateway (Kong)
  ↓
  ├─→ Semantic Core ──→ Knowledge Graph ──→ External Systems
  │                         ↑
  ├─→ Context Analyzer ─────┤
  │         ↓
  ├─→ Recommendation Algorithm ←── User Feedback (async)
  │         ↓
  ├─→ Artifact Engine ──→ CADSL Runtime ──→ Web App
  │         ↑                  ↑
  ├─→ Documentation Orchestrator
  │         ↓
  ├─→ Project Context Analyzer ──→ Semantic Core
  │                            └──→ CALM CLI
  ├─→ AI Agent Config
  └─→ CALM CLI

Comparison with SEA-Forge™ Vision

Pillar Mapping

Key Evolution Points

1. Consolidation: 11 services → 5 conceptual pillars in SEA-Forge™
2. Abstraction: Service implementation details hidden behind pillar interfaces
3. Expansion: New capabilities (polyglot DSL, runtime governance, portfolio intelligence)
4. Simplification: Cleaner conceptual model for users

Deployment Considerations

Scalability Hotspots

• CADSL Runtime & Renderer: Frontend traffic concentrator
• Knowledge Graph Service: Complex graph queries
• Recommendation Algorithm: Compute-intensive

Data Stores (Implied)

• Oxigraph: Primary knowledge graph
• PostgreSQL: Relational data (user accounts, configurations)
• Redis: Caching (likely, not shown)

Observability Needs

• Health checks at /actuator/health (Spring Boot pattern)
• Distributed tracing across 11 services
• Log aggregation

Migration Path to SEA-Forge™

Phase 1: Consolidate Cognitive Services

• Merge Context Analyzer, Recommendation Algorithm, Artifact Engine into unified SEA™ Core Cognitive Module

Phase 2: Enhance Semantic Core

• Evolve Semantic Core + DSL Management into DomainForge™ with polyglot support

Phase 3: Split Governance

• Extract runtime governance from CALM CLI into GovernedSpeed™
• Keep architectural validation in SEA™ Core

Phase 4: Unify Documentation

• Consolidate Documentation services into VibesPro™ App Generator

Phase 5: Add Executive Layer

• Introduce IAGPM for portfolio intelligence

Related Specifications

• ANALYSIS-001: SEA™ Original Domain Analysis - DDD analysis of 15 bounded contexts
• VISION-001: SEA-Forge™ Master Vision - Evolution to 5-pillar architecture
• ADR-001: Core Principles - Architectural foundation
• ADR-002: Frontend Framework - Remix over Next.js decision

Diagram Source

Format: PlantUML C4 Container Diagram
File: documentation/working/09-working-documents/c4-container-v5.puml

Rendering Instructions

1
2
3
4
5
# Using PlantUML CLI
plantuml c4-container-v5.puml

# Using online renderer
# Upload to https://www.plantuml.com/plantuml/uml/

Dependencies:

• C4-PlantUML library: https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Notes for SEA-Forge™ Developers

1. Service Boundaries Are Stable: Even if implementation consolidates, respect these logical boundaries
2. Integration Patterns Proven: Kong + FastAPI + Oxigraph pattern works well
3. Async Feedback Loop Critical: Message queue for user feedback enables learning
4. Go for Performance: Consider Go for compute-intensive governance tasks
5. TypeScript Bridge: TypeScript/Node.js for frontend-adjacent services

Status: This represents the historical SEA™ architecture. Current SEA-Forge™ development should reference VISION-001 for the target architecture.