Architecture Overview

CODITECT system design and component relationships.

Last Updated: December 22, 2025 Status: Production Ready Framework Version: CODITECT v1.7.2 + UAF v2.0

System Overview
Distributed Intelligence Architecture
Core Systems
Integration Patterns
Technology Stack

Specification

Configuration Options

Option	Type	Default	Description
`option1`	string	`"default"`	First option
`option2`	int	`10`	Second option
`option3`	bool	`true`	Third option

System Overview

What is CODITECT?

CODITECT (Comprehensive Development & Integration Technology for Execution, Coordination, and Tracking) transforms ideas into production-ready products through:

AI-Powered Multi-Agent System - Specialized agents for different tasks
Intelligent Orchestration - Automated workflow coordination
Production Standards Enforcement - Quality scoring and validation
Multi-Session Continuity - Zero catastrophic forgetting
Work Reuse Optimization - 50-90% efficiency gains

Core Principles

Distributed Intelligence - Components distributed via symlinks
Progressive Disclosure - Load documentation on-demand
Manual Activation - Explicit component activation
Zero Data Loss - Session preservation with deduplication
Production-Ready by Default - Enforced quality standards

Distributed Intelligence Architecture

Symlink Chain Architecture

CODITECT uses symlinks for distributed intelligence:

coditect-rollout-master/
├── .coditect -> submodules/core/coditect-core    # Brain
├── .claude -> .coditect                          # Compatibility
│
└── submodules/core/coditect-core/
    ├── .coditect -> /path/to/parent/.coditect   # Parent reference
    ├── .claude -> .coditect                     # Self-reference
    ├── agents/                                   # All agents
    ├── commands/                                 # All commands
    ├── skills/                                   # All skills
    └── scripts/                                  # All scripts

Key Insight: .claude IS .coditect - same directory via different symlinks.

Why Distributed?

Benefits:

Reusability: Framework accessible from any submodule
Consistency: Single source of truth
Maintainability: Update once, propagate everywhere
Flexibility: Projects can reference parent or local CODITECT

How it works:

Master repo contains CODITECT brain
Submodules reference via symlink
All projects share same component library
Updates propagate automatically

Core Systems

1. Multi-Agent Orchestration System

Purpose: Coordinate specialized agents for complex workflows

Components:

orchestrator agent - Planning and coordination
Specialized agents - Domain-specific execution
Task() invocation pattern - Verified working method
Agent discovery service - Capability-based routing

Example workflow:

# Step 1: Planning
Task(subagent_type="orchestrator",
     description="Plan deployment",
     prompt="Create deployment plan with agent assignments")

# Step 2: Execution (parallel)
Task(subagent_type="codi-devops-engineer", ...)
Task(subagent_type="cloud-architect", ...)

# Step 3: Verification
Task(subagent_type="codi-documentation-writer", ...)

2. Session Preservation System

Purpose: Zero data loss across sessions via deduplication

Components:

message_deduplicator.py - Core deduplication engine
JSONL processing - Large session handling
/export-dedup command - Daily session exports
/process-jsonl-sessions - Batch processing

How it works:

Export session to text or process JSONL
Parse messages (user + assistant)
Compute SHA-256 hash for each message
Compare against global hash pool
Store only unique messages
Track dedup statistics

Storage:

MEMORY-CONTEXT/dedup_state/
├── global_hashes.json          # Hash pool
├── unique_messages.jsonl       # Unique messages
├── session_watermarks.json     # Resume tracking
└── dedup_stats.json           # Statistics

3. Component Activation System

Purpose: Manual, explicit component lifecycle management

Components:

.coditect/component-activation-status.json - Activation registry
update-component-activation.py - CLI management tool
scripts/session-startup.py - Session initialization

Workflow:

# Activate component
python3 scripts/update-component-activation.py activate agent agent-name \
  --reason "Why activation needed"

# Commit activation
git add .coditect/component-activation-status.json
git commit -m "chore: Activate agent-name"

# Next session: component auto-loads

4. Production Folder Organization System

Purpose: Enforce production-ready project structures

Components:

project-organizer agent - Structure optimization
folder-organization skill - Scoring and validation
validate-folder-organization.py - Validation script
40/40 quality standard - Minimum production threshold

Scoring:

0-20 points: Prototype
21-39 points: Development
40-59 points: Production-ready (minimum)
60-79 points: Well-organized
80-100 points: Exemplary

5. Git Workflow Automation System

Purpose: Bottom-up git synchronization with conflict detection

Components:

git-workflow-orchestrator agent - Orchestration
/git-sync command - User interface
git-workflow.py - 5-phase execution script
pre-push-submodule-check.sh - Safety hook

5-Phase Process:

Discovery (codebase-locator) - Analyze submodules
Planning (codi-documentation-writer) - Generate commits
Execution (git-workflow-orchestrator) - Sync bottom-up
Master Update (git-workflow-orchestrator) - Update pointers
Verification (codi-documentation-writer) - Generate reports

Integration Patterns

Pattern 1: Agent Coordination

Problem: Complex tasks require multiple agents

Solution: Orchestrator pattern with dependency resolution

# Orchestrator creates plan
plan = Task(subagent_type="orchestrator", ...)

# Execute phases in order
for phase in plan.phases:
    Task(subagent_type=phase.agent, ...)

Pattern 2: Progressive Disclosure

Problem: Loading all documentation consumes tokens

Solution: Read documentation on-demand

# ✅ DO: Load as needed
When task requires X:
    Read(file_path="docs/specific-guide.md")

# ❌ DON'T: Load everything at start
Read all documentation files

Pattern 3: Component Discovery

Problem: Recreating existing solutions wastes tokens

Solution: Search before creating

# Step 1: Search
results = Grep(pattern="feature-domain", glob="**/*.md")

# Step 2: Evaluate
for result in results:
    component = Read(file_path=result)
    if fitness > 70%:
        reuse(component)
    else:
        create_new()

Pattern 4: Multi-Session Continuity

Problem: Context loss between sessions

Solution: Session preservation + git history

# End of session
/export-dedup
/create-checkpoint "Work description"

# Start of session
./scripts/init.sh
git log --oneline | head -10
# Review previous work

Pattern 5: Work Reuse Optimization

Problem: Repeated work wastes tokens

Solution: Deduplication + component library

Dedup rate metrics:

60-80% = Good reuse (mature project)
40-60% = Mixed (refactoring)
20-40% = High uniqueness (new project)
<20% = Possibly recreating solutions
95% = Repeated work without progress

Technology Stack

Core Technologies

Layer	Technology	Purpose
AI	Claude Sonnet 4.5	Agent reasoning
Runtime	Python 3.10+	Framework execution
CLI	Anthropic Claude Code	User interface
Storage	JSON/JSONL	Data persistence
VCS	Git 2.25+	Version control
Container	Docker + Docker Compose	Dev environment

Framework Structure

CODITECT Framework
├── Presentation Layer
│   ├── Slash Commands
│   └── AI Command Router
│
├── Application Layer
│   ├── Multi-Agent System
│   └── Orchestration Engine
│
├── Domain Layer
│   ├── Production Skills
│   └── Automation Scripts
│
└── Infrastructure Layer
    ├── Session Preservation
    ├── Component Activation
    └── Git Workflow Automation

Performance Characteristics

Token Efficiency

Claude.md optimization:

Before: 1,866 lines (18,660 tokens × 100 turns = 1,866,000 tokens)
Target: 150 lines (1,500 tokens × 100 turns = 150,000 tokens)
Savings: 92% reduction, 1,716,000 tokens saved

Component activation:

Lean activation: 10-15 components
Context window savings: ~50% vs. full activation
Startup speed: <5 seconds

Deduplication Performance

Text exports:

Average speed: ~1,000 messages/second
Memory: <100 MB
Typical dedup rate: 60-80%

JSONL batch processing:

Speed: ~1,000 lines/second
Memory: <1 GB peak
Largest tested: 89 MB, 15,906 lines, <30 seconds

Scalability

Current limits:

Components managed: See config/component-counts.json
Unique messages deduplicated: 7,500+
JSONL sessions processed: 100+ MB
Projects in master repository: 50+

Configuration

CODITECT framework configuration settings and parameters.

Parameter	Type	Default	Description
`activation_mode`	string	`manual`	Component activation mode: `manual`, `auto`, `lazy`
`dedup_enabled`	boolean	`true`	Enable message deduplication
`dedup_threshold`	float	`0.95`	Similarity threshold for deduplication (0.0-1.0)
`session_export_format`	string	`jsonl`	Session export format: `jsonl`, `text`, `json`
`max_context_window`	integer	`200000`	Maximum context window size (tokens)
`component_load_mode`	string	`progressive`	Component loading: `progressive`, `eager`, `lazy`
`git_sync_mode`	string	`bottom-up`	Git sync strategy: `bottom-up`, `top-down`, `parallel`
`quality_threshold`	integer	`40`	Minimum quality score for production (0-100)
`orchestrator_timeout`	integer	`300`	Agent orchestration timeout (seconds)
`memory_retention_days`	integer	`90`	Session memory retention period (days)

Environment Variables

Variable	Type	Description
`CODITECT_HOME`	path	Root directory for CODITECT framework
`CODITECT_ACTIVATION_MODE`	string	Override activation mode
`CODITECT_LOG_LEVEL`	string	Logging level: `DEBUG`, `INFO`, `WARN`, `ERROR`
`CODITECT_ENABLE_TELEMETRY`	boolean	Enable usage telemetry collection

API Reference

Core Framework APIs

Component Activation API

# Activate component
python3 scripts/update-component-activation.py activate <type> <name> --reason "purpose"

# Parameters:
# - type: Component type (agent, command, skill, script, hook)
# - name: Component name
# - reason: Activation justification

Session Preservation API

# Export session with deduplication
/export-dedup

# Process JSONL sessions
/process-jsonl-sessions --batch --min-size <size>

# Parameters:
# - batch: Process multiple sessions
# - min-size: Minimum file size (MB)

Git Workflow API

# Synchronize repositories
/git-sync --target <target> --mode <mode>

# Parameters:
# - target: Sync target (all, submodule-name, current)
# - mode: Sync mode (full, analyze, dry-run)

Agent Invocation API

# Invoke specialized agent
/agent <agent-name> <task-description>

# Python API
from scripts.core.invoke_agent import invoke_agent
result = invoke_agent(agent_name="orchestrator", task="coordinate deployment")

Orchestrator API

# Coordinate multi-agent workflow
from scripts.core.orchestrator import coordinate_workflow

result = coordinate_workflow(
    workflow_name="deployment-pipeline",
    phases=["build", "test", "deploy"],
    agents=["devops-engineer", "security-specialist", "codi-qa-specialist"]
)

# Parameters:
# - workflow_name (str): Name of workflow to execute
# - phases (List[str]): Ordered phases to execute
# - agents (List[str]): Agents to coordinate
# Returns: WorkflowResult with status, outputs, and metrics

Session Preservation API

# Preserve session context
from scripts.core.session_manager import preserve_session

preserve_session(
    session_id="current",
    include_messages=True,
    include_decisions=True,
    export_format="jsonl"
)

# Parameters:
# - session_id (str): Session identifier
# - include_messages (bool): Include message history
# - include_decisions (bool): Include extracted decisions
# - export_format (str): Output format (jsonl, json, text)
# Returns: SessionExport with path and statistics

Quality Scoring API

# Validate folder organization
python3 scripts/validate-folder-organization.py <directory>

# Returns: Score (0-100), recommendations, quality tier

Schema Reference

Component Activation Schema

{
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "Component name"},
    "type": {"type": "string", "enum": ["agent", "command", "skill", "script", "hook"]},
    "activated": {"type": "boolean", "default": false},
    "version": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$"},
    "status": {"type": "string", "enum": ["operational", "degraded", "offline"]},
    "activated_at": {"type": "string", "format": "date-time"}
  },
  "required": ["name", "type", "activated"]
}

Session Export Schema

{
  "type": "object",
  "properties": {
    "session_id": {"type": "string"},
    "messages": {"type": "array"},
    "decisions": {"type": "array"},
    "timestamp": {"type": "string", "format": "date-time"},
    "dedup_stats": {"type": "object"}
  }
}

Additional Resources

Architecture Documentation

Component Reference - Complete component inventory
Claude 4.5 Guide - Claude 4.5 integration patterns

Integration Guides

Component Activation Guide - Using components
Memory Management Guide - Context preservation
Git Workflow Automation Guide - Submodule sync

Document Status: Production Ready Framework Version: CODITECT v1.7.2 + UAF v2.0 (dev) Next Review: March 2026

Table of Contents​

Specification​

Configuration Options​

System Overview​

What is CODITECT?​

Core Principles​

Distributed Intelligence Architecture​

Symlink Chain Architecture​

Why Distributed?​

Core Systems​

1. Multi-Agent Orchestration System​

2. Session Preservation System​

3. Component Activation System​

4. Production Folder Organization System​

5. Git Workflow Automation System​

Integration Patterns​

Pattern 1: Agent Coordination​

Pattern 2: Progressive Disclosure​

Pattern 3: Component Discovery​

Pattern 4: Multi-Session Continuity​

Pattern 5: Work Reuse Optimization​

Technology Stack​

Core Technologies​

Framework Structure​

Performance Characteristics​

Token Efficiency​

Deduplication Performance​

Scalability​

Configuration​

Environment Variables​

API Reference​

Core Framework APIs​

Component Activation API​

Session Preservation API​

Git Workflow API​

Agent Invocation API​

Orchestrator API​

Session Preservation API​

Quality Scoring API​

Schema Reference​

Component Activation Schema​

Session Export Schema​

Additional Resources​

Architecture Documentation​

Integration Guides​

Table of Contents

Specification

Configuration Options

System Overview

What is CODITECT?

Core Principles

Distributed Intelligence Architecture

Symlink Chain Architecture

Why Distributed?

Core Systems

1. Multi-Agent Orchestration System

2. Session Preservation System

3. Component Activation System

4. Production Folder Organization System

5. Git Workflow Automation System

Integration Patterns

Pattern 1: Agent Coordination

Pattern 2: Progressive Disclosure

Pattern 3: Component Discovery

Pattern 4: Multi-Session Continuity

Pattern 5: Work Reuse Optimization

Technology Stack

Core Technologies

Framework Structure

Performance Characteristics

Token Efficiency

Deduplication Performance

Scalability

Configuration

Environment Variables

API Reference

Core Framework APIs

Component Activation API

Session Preservation API

Git Workflow API

Agent Invocation API

Orchestrator API

Session Preservation API

Quality Scoring API

Schema Reference

Component Activation Schema

Session Export Schema

Additional Resources

Architecture Documentation

Integration Guides