SousChef Architecture Declaration

Version: 2.0 Last Updated: 2026-03-06 Status: Approved & Enforced via SonarCloud

This document is the authoritative architectural declaration for SousChef. All code must adhere to the structure, dependencies, and boundaries defined here.

Quick Navigation

Architectural Vision
Layered Architecture
Container Definitions
Dependency Matrix
Module Placement Rules
SonarCloud Enforcement
Growth Guidelines

Architectural Vision

SousChef is evolving from a Chef-to-Ansible converter into a multi-source, multi-target infrastructure-as-code transformation platform with enterprise features:

Transformation Capabilities (Current & Planned)

✅ Chef → Ansible (current)
✅ Puppet → Ansible (current)
✅ Salt → Ansible (current)
✅ Bash scripts → Ansible
✅ PowerShell scripts → Ansible
🔄 Multi-target: Ansible, Terraform, CloudFormation (via IR)

Enterprise Features (Current & Planned)

🔄 REST API - Programmatic access to all capabilities
✅ Authentication & RBAC - Role-based access control
✅ Audit Logging - Compliance and change tracking
🔄 Team Collaboration - Multi-user workflows
🔄 Performance Benchmarking - Profiling and optimisation metrics
✅ Integrations - GitHub, SCM, ticketing, notifications
✅ UI Enhancements - Dark mode, accessibility, analytics, AI recommendations

Design Principles

Separation of Concerns - Each container handles one responsibility
Dependency Discipline - Lower layers never depend on higher layers
Plugin Architecture - Extensible parser/generator framework via IR
API-First - All features accessible via REST API
Security by Design - Auth, RBAC, and audit at the core
Observable - Performance metrics, logging, and analytics throughout

Layered Architecture

SousChef follows a strict layered architecture where dependencies only flow downward. Higher layers can depend on lower layers, but never the reverse.

┌─────────────────────────────────────────────────────────────┐
│ LAYER 7: User Interfaces                                    │
│ cli/, ui/, server.py (MCP)                                  │
│ (Depends on: orchestrators, api)                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ LAYER 6: Orchestration                                      │
│ orchestrators/, assessment.py, deployment.py                │
│ (Depends on: parsers, converters, generators, integrations) │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ LAYER 5: Integration & API                                  │
│ api/, integrations/                                         │
│ (Depends on: auth, audit, storage, orchestrators)          │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ LAYER 4: Services                                           │
│ auth/, audit/, benchmarking/                                │
│ (Depends on: core, storage)                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ LAYER 3: Domain Logic                                       │
│ parsers/, converters/, generators/                          │
│ (Depends on: core, ir, storage, filesystem)                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ LAYER 2: Data & Infrastructure                              │
│ storage/, filesystem/, ir/                                  │
│ (Depends on: core)                                          │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ LAYER 1: Foundation                                         │
│ core/                                                       │
│ (No dependencies - provides utilities, constants, errors)   │
└─────────────────────────────────────────────────────────────┘

Container Definitions

Layer 1: Foundation

`core/` - Shared Utilities

Purpose: Foundation layer providing reusable utilities, constants, and base classes. Status: ✅ Exists Dependencies: None (foundation layer) Contains:

constants.py - Application-wide constants
errors.py - Custom exception classes
path_utils.py - Path normalization and validation
ruby_utils.py - Ruby value parsing utilities
validation.py - Input validation helpers
ansible_versions.py - Ansible version compatibility data
metrics.py - Effort/timeline calculation utilities
logging.py - Logging configuration
caching.py - Caching mechanisms

Rules:

❌ NEVER import from any other souschef module
✅ Only import from Python stdlib and third-party libraries
✅ Keep logic minimal - utilities only, no business logic

Layer 2: Data & Infrastructure

`storage/` - Data Persistence

Purpose: Database and blob storage abstractions. Status: ✅ Exists (database.py, blob.py) Dependencies: core/ Contains:

database.py - PostgreSQL/SQLite database access
blob.py - Object storage (MinIO/S3) access
models.py - Data models and ORM definitions

Rules:

✅ Can import from: core/
❌ Cannot import from: any other containers

`filesystem/` - File Operations

Purpose: Safe file system operations with validation. Status: ✅ Exists Dependencies: core/ Contains:

operations.py - Directory/file operations with safety checks

Rules:

✅ Can import from: core/
❌ Cannot import from: any other containers

`ir/` - Intermediate Representation

Purpose: Abstract, tool-agnostic representation of infrastructure configurations. Status: ✅ Exists Dependencies: core/ Contains:

schema.py - IRGraph, IRNode, IRAction data structures
versioning.py - Version management and schema evolution
plugin.py - SourceParser/TargetGenerator plugin framework

Rules:

✅ Can import from: core/
❌ Cannot import from: any other containers
🎯 Key Design: Tool-agnostic - no Chef/Puppet/Ansible-specific code

Layer 3: Domain Logic

`parsers/` - Input Parsing

Purpose: Extract structured data from source configuration management tools. Status: ✅ Exists (Chef parsers, PowerShell parser, Bash parser, Puppet parser, Salt parser) Dependencies: core/, ir/, filesystem/ Contains:

recipe.py - Chef recipe parser
metadata.py - Chef metadata parser
attributes.py - Chef attributes parser
template.py - ERB template parser
habitat.py - Habitat plan parser
inspec.py - InSpec profile parser
ansible_inventory.py - Ansible inventory parser
✅ puppet.py - Puppet manifest parser (14 recognised resource types, 10 mapped to Ansible modules, unsupported construct detection)
✅ salt.py - Salt state parser
✅ bash.py - Bash script parser (13 operation categories, confidence scoring, sensitive data detection)
✅ powershell.py - PowerShell script parser

Rules:

✅ Can import from: core/, ir/, filesystem/
❌ Cannot import from: converters/, generators/, orchestrators/, api/, ui/, cli/
🎯 Key Design: Read-only - extract structure without transformation

`converters/` - Transformation Logic

Purpose: Transform parsed data into intermediate or target formats. Status: ✅ Exists (Chef→Ansible, PowerShell→Ansible, Bash→Ansible, Puppet→Ansible); 🔄 Planned (multi-target) Dependencies: core/, parsers/, ir/ Contains:

playbook.py - Recipe → Ansible playbook
resource.py - Resource → Ansible task
habitat.py - Habitat → Docker
template.py - ERB → Jinja2
conversion_rules.py - Transformation rules engine
✅ puppet_to_ansible.py - Puppet → Ansible (10 resource types fully mapped + AI-assisted conversion for complex constructs)
✅ salt.py - Salt → Ansible conversion and fallback handling
✅ powershell.py - PowerShell → Ansible (exists)
✅ bash_to_ansible.py - Bash → Ansible (exists)

Rules:

✅ Can import from: core/, parsers/, ir/
❌ Cannot import from: generators/, orchestrators/, api/, ui/, cli/
🎯 Key Design: Pure transformation - no I/O, no orchestration

`generators/` - Output Generation

Purpose: Generate target configuration files from IR or converter output. Status: ✅ Exists (repo.py, powershell.py) Dependencies: core/, converters/, ir/, filesystem/ Contains:

repo.py - Ansible repository structure generation
✅ powershell.py - Windows inventory, group_vars, requirements.yml, role skeleton, AWX job template, fidelity report
🔄 terraform.py - Terraform module generation (planned)
🔄 cloudformation.py - CloudFormation template generation (planned)

Rules:

✅ Can import from: core/, converters/, ir/, filesystem/
❌ Cannot import from: orchestrators/, api/, ui/, cli/

Layer 4: Services

`auth/` - Authentication & Authorization

Purpose: User authentication, role-based access control (RBAC). Status: ✅ Partial (RBAC role/permission enforcement) Dependencies: core/, storage/ Contains:

✅ rbac.py - Role and permission management
🔄 authentication.py - User login/logout, session management (planned)
🔄 tokens.py - JWT token generation and validation (planned)
🔄 policies.py - Access policy definitions (planned)

Rules:

✅ Can import from: core/, storage/
❌ Cannot import from: domain logic, orchestrators, integrations, UI

`audit/` - Audit Logging

Purpose: Compliance, change tracking, audit trail. Status: ✅ Partial (event logging and workspace audit trail) Dependencies: core/, storage/, auth/ Contains:

✅ events.py - Audit event definitions and logging helpers
🔄 logger.py - Dedicated audit logger abstraction (planned)
🔄 compliance.py - Compliance report generation (planned)

Rules:

✅ Can import from: core/, storage/, auth/
❌ Cannot import from: domain logic, orchestrators, integrations, UI

`benchmarking/` - Performance Metrics

Purpose: Performance profiling, benchmarking, optimisation metrics. Status: ✅ Exists (profiling.py - needs migration) Dependencies: core/, storage/ Contains:

profiler.py - Code execution profiling
metrics.py - Performance metric collection
reports.py - Benchmark report generation

Rules:

✅ Can import from: core/, storage/
❌ Cannot import from: domain logic, orchestrators, integrations, UI

Layer 5: Integration & API

`integrations/` - External Systems

Purpose: Integration with GitHub, GitLab, AWX, Jira, Slack, etc. Status: ✅ Partial (SCM, ticket sync, notifications, GitHub agent control) Dependencies: core/, auth/, audit/, storage/ Contains:

✅ github/ - GitHub API client and workflows
✅ scm_connector.py - GitHub/GitLab external reference connector
✅ ticket_sync.py - Jira/ServiceNow ticket sync with retry handling
✅ notification_dispatch.py - Slack/Teams notification dispatch
🔄 gitlab.py - GitLab API integration (planned)
🔄 awx.py - AWX/Tower API client (planned)
🔄 jira.py - Jira issue tracking (planned)
🔄 slack.py - Slack notifications (planned)

Rules:

✅ Can import from: core/, auth/, audit/, storage/
❌ Cannot import from: domain logic (parsers/converters), orchestrators, UI

`api/` - REST API

Purpose: RESTful API for programmatic access to all platform capabilities. Status: 🔄 Planned Dependencies: core/, auth/, audit/, storage/, orchestrators/ Contains:

routes/ - API endpoint definitions
schemas.py - Request/response schemas (Pydantic)
middleware.py - Authentication, rate limiting, CORS
docs.py - OpenAPI/Swagger documentation

Rules:

✅ Can import from: core/, auth/, audit/, storage/, orchestrators/
❌ Cannot import from: cli/, ui/, server.py (MCP)
🎯 Key Design: Stateless, RESTful, versioned (/v1/, /v2/)

Layer 6: Orchestration

`orchestrators/` - Workflow Coordination

Purpose: High-level workflows coordinating parsers, converters, generators. Status: ✅ Partial (assessment.py, deployment.py as top-level); 🔄 Needs refactor Dependencies: core/, parsers/, converters/, generators/, integrations/, storage/ Contains:

migration.py - End-to-end migration workflows
analysis.py - Codebase analysis orchestration
validation.py - Multi-stage validation workflows
deployment.py - Deployment orchestration (refactored from top-level)
assessment.py - Assessment workflows (refactored from top-level)

Rules:

✅ Can import from: core/, parsers/, converters/, generators/, integrations/, storage/, auth/, audit/, benchmarking/
❌ Cannot import from: api/, cli/, ui/, server.py
🎯 Key Design: Coordinates lower layers, implements business workflows

Layer 7: User Interfaces

`cli/` - Command-Line Interface

Purpose: Terminal-based user interface. Status: ✅ Exists (cli.py, cli_v2_commands.py, cli_registry.py - needs consolidation) Dependencies: orchestrators/, api/ (optional) Contains:

commands/ - CLI command implementations
interactive.py - Interactive mode (prompts, wizards)

Rules:

✅ Can import from: orchestrators/, api/ (if using REST API), core/
❌ Cannot import from: ui/, server.py, domain logic directly
🎯 Key Design: Thin wrapper around orchestrators

`ui/` - Web User Interface

Purpose: Browser-based dashboard and visualizations. Status: ✅ Exists (Streamlit with analytics, recommendations, dark/high-contrast themes) Dependencies: api/, orchestrators/ Contains:

app.py - Main Streamlit application
pages/ - Dashboard pages
components/ - Reusable UI components
✅ analytics.py - Usage analytics and insights
✅ recommendations.py - AI-powered smart recommendations
✅ theme.py - Dark mode and accessibility themes

Rules:

✅ Can import from: api/, orchestrators/ (for direct calls during prototyping), core/
❌ Cannot import from: cli/, server.py, domain logic directly
🎯 Key Design: API-first - all actions call REST API (when available)

`server.py` - MCP Server (Top-Level File)

Purpose: Model Context Protocol server entry point. Status: ✅ Exists Dependencies: orchestrators/, core/ Contains:

MCP tool registration using FastMCP
Tool wrapper functions calling orchestrators

Rules:

✅ Can import from: orchestrators/, core/
❌ Cannot import from: cli/, ui/, domain logic directly
🎯 Key Design: Thin MCP wrapper around orchestrators

Dependency Matrix

This matrix defines which containers CAN import from which other containers. Use this when implementing Phase 2 in SonarCloud.

Legend:

✅ = Allowed dependency
❌ = Forbidden dependency
🔄 = Conditional (e.g., only during certain phases)

From ↓ / To →	core	storage	filesystem	ir	parsers	converters	generators	auth	audit	benchmarking	integrations	api	orchestrators	cli	ui	server.py
core	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
storage	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
filesystem	✅	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
ir	✅	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
parsers	✅	❌	✅	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
converters	✅	❌	❌	✅	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
generators	✅	❌	✅	✅	❌	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
auth	✅	✅	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌
audit	✅	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌	❌
benchmarking	✅	✅	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌
integrations	✅	✅	❌	❌	❌	❌	❌	✅	✅	❌	✅	❌	❌	❌	❌	❌
api	✅	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌	✅	✅	❌	❌	❌
orchestrators	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	❌	✅	❌	❌	❌
cli	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	🔄	✅	✅	❌	❌
ui	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	✅	🔄	❌	✅	❌
server.py	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	✅

Matrix Validation Rules

Foundation Layer (core):

✅ Can import: Only Python stdlib and third-party libraries
❌ Cannot import: Any souschef module

Data Layer (storage, filesystem, ir):

✅ Can import: core/ only
❌ Cannot import: Any higher layer

Domain Layer (parsers, converters, generators):

✅ Can import: core/, ir/, filesystem/ (parsers, generators only), parsers/ (converters only), converters/ (generators only)
❌ Cannot import: Services, integrations, orchestrators, UI layers

Service Layer (auth, audit, benchmarking):

✅ Can import: core/, storage/, sometimes each other (audit→auth)
❌ Cannot import: Domain logic, orchestrators, UI layers

Integration & API Layer:

✅ Can import: Foundation, data, services, orchestrators (API only)
❌ Cannot import: Domain logic directly, UI layers

Orchestration Layer:

✅ Can import: All lower layers except API/UI interfaces
❌ Cannot import: api/, cli/, ui/, server.py

UI Layer (cli, ui, server.py):

✅ Can import: orchestrators/, api/ (UI only), core/
❌ Cannot import: Domain logic directly, other UI containers

Module Placement Rules

Use this decision tree when creating new code:

NEW FEATURE/CODE
     │
     ├─ Is it a utility/constant/base class?
     │  └─ YES → core/
     │
     ├─ Does it store/retrieve data?
     │  └─ YES → storage/ or filesystem/
     │
     ├─ Does it parse input files?
     │  └─ YES → parsers/ (e.g., parsers/puppet.py)
     │
     ├─ Does it transform data without I/O?
     │  └─ YES → converters/ or generators/
     │
     ├─ Is it authentication/authorization?
     │  └─ YES → auth/
     │
     ├─ Is it audit logging/compliance?
     │  └─ YES → audit/
     │
     ├─ Is it performance profiling?
     │  └─ YES → benchmarking/
     │
     ├─ Is it an external system integration?
     │  └─ YES → integrations/ (e.g., integrations/gitlab.py)
     │
     ├─ Is it a REST API endpoint?
     │  └─ YES → api/routes/
     │
     ├─ Does it coordinate multiple lower layers?
     │  └─ YES → orchestrators/
     │
     └─ Is it a user interface?
        ├─ CLI? → cli/commands/
        ├─ Web? → ui/pages/ or ui/components/
        └─ MCP? → server.py (top-level file)

Examples

Puppet Support (Implemented):

✅ parsers/puppet.py - Parse Puppet manifests → structured data (14 recognised resource types, 10 fully mapped to Ansible)
✅ converters/puppet_to_ansible.py - Puppet → Ansible via ansible.builtin modules
✅ ui/pages/puppet_migration.py - Streamlit UI page for manifest/module conversion
✅ 8 MCP tools in server.py — parse, convert, list types, AI-assisted conversion
✅ CLI commands via souschef puppet subcommand group
🔄 orchestrators/migration.py - Full Puppet workflow orchestration (planned)
🔄 api/routes/puppet.py - REST endpoints for Puppet conversion (planned)

Adding RBAC:

auth/rbac.py - Role and permission management
auth/policies.py - Policy definitions
api/middleware.py - Update to enforce RBAC on endpoints
audit/logger.py - Log permission checks
ui/components/permissions.py - UI for role assignment

Adding Dark Mode:

ui/theme.py - Theme definitions and switcher
ui/components/*.py - Update components to use theme context
api/routes/user_preferences.py - Store user theme preference

SonarCloud Enforcement

Phase 1: Container-Level (Current)

Status: ✅ Implemented in UI

Containers defined:

souschef/core
souschef/parsers
souschef/converters
souschef/filesystem
souschef/ir

Next Steps:

Add remaining containers to Phase 1:
- souschef/storage
- souschef/generators
- souschef/auth (create skeleton)
- souschef/audit (create skeleton)
- souschef/benchmarking (migrate profiling.py)
- souschef/integrations (existing github/)
- souschef/api (create skeleton)
- souschef/orchestrators (create + migrate assessment.py, deployment.py)
- souschef/cli (consolidate existing files)
- souschef/ui
Define relationships in SonarCloud UI based on Dependency Matrix above

Phase 2: File-Level (Future)

Define individual modules within containers for granular enforcement

Example:

souschef/parsers/recipe.py can depend on souschef/core/path_utils.py
souschef/parsers/recipe.py cannot depend on souschef/converters/playbook.py

Growth Guidelines

When Adding New Capabilities

1. Start with Architecture

Is this a new container or fits in existing?
What dependencies does it need?
Check Dependency Matrix for violations

2. Create Container Skeleton (if new)

# souschef/newcontainer/__init__.py
"""
NewContainer: Brief description

Purpose: What this container does
Dependencies: Which containers it can import from
Rules: What it cannot do
"""

__version__ = "1.0.0"

3. Update Architecture Document

Add to Container Definitions
Update Dependency Matrix
Add to Module Placement Rules decision tree

4. Implement with Discipline

Follow dependency rules strictly
Write tests in tests/unit/test_newcontainer.py
Update integration tests if needed

5. Update SonarCloud

Add container to architecture definition
Define allowed dependencies
Verify no violations detected

When Refactoring Existing Code

Current Violations to Fix:

Top-Level Files (assessment.py, deployment.py, ansible_upgrade.py, profiling.py)
- Issue: Not in containers, hard to govern
- Solution: Migrate to orchestrators/ or appropriate container
- Timeline: v2.1 refactor sprint
CLI Consolidation (cli.py, cli_v2_commands.py, cli_registry.py)
- Issue: Fragmented CLI code
- Solution: Consolidate into cli/ container
- Timeline: v2.1 refactor sprint
Profiling Migration (profiling.py → benchmarking/)
- Issue: Not in proper service container
- Solution: Move to benchmarking/profiler.py
- Timeline: v2.0 completion

Migration Checklist

When moving code between containers:

Verify new location follows Dependency Matrix
Update all imports in dependent modules
Move tests to mirror new structure
Update API documentation if endpoints change
Add deprecation notices for old imports (if public API)
Update SonarCloud architecture definition
Run full test suite
Update CHANGELOG.md

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

SousChef Architecture Declaration

Quick Navigation

Architectural Vision

Transformation Capabilities (Current & Planned)

Enterprise Features (Current & Planned)

Design Principles

Layered Architecture

Container Definitions

Layer 1: Foundation

core/ - Shared Utilities

Layer 2: Data & Infrastructure

storage/ - Data Persistence

filesystem/ - File Operations

ir/ - Intermediate Representation

Layer 3: Domain Logic

parsers/ - Input Parsing

converters/ - Transformation Logic

generators/ - Output Generation

Layer 4: Services

auth/ - Authentication & Authorization

audit/ - Audit Logging

benchmarking/ - Performance Metrics

Layer 5: Integration & API

integrations/ - External Systems

api/ - REST API

Layer 6: Orchestration

orchestrators/ - Workflow Coordination

Layer 7: User Interfaces

cli/ - Command-Line Interface

ui/ - Web User Interface

server.py - MCP Server (Top-Level File)

Dependency Matrix

Matrix Validation Rules

Module Placement Rules

Examples

SonarCloud Enforcement

Phase 1: Container-Level (Current)

Phase 2: File-Level (Future)

Growth Guidelines

When Adding New Capabilities

When Refactoring Existing Code

Migration Checklist

Related Documentation

`core/` - Shared Utilities

`storage/` - Data Persistence

`filesystem/` - File Operations

`ir/` - Intermediate Representation

`parsers/` - Input Parsing

`converters/` - Transformation Logic

`generators/` - Output Generation

`auth/` - Authentication & Authorization

`audit/` - Audit Logging

`benchmarking/` - Performance Metrics

`integrations/` - External Systems

`api/` - REST API

`orchestrators/` - Workflow Coordination

`cli/` - Command-Line Interface

`ui/` - Web User Interface

`server.py` - MCP Server (Top-Level File)