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

---

Table of Contents

1. System Overview
2. Distributed Intelligence Architecture
3. Core Systems
4. Integration Patterns
5. 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 H.P.001-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

1. Distributed Intelligence - Components distributed via symlinks
2. Progressive Disclosure - Load documentation on-demand
3. Manual Activation - Explicit component activation
4. Zero Data Loss - Session preservation with deduplication
5. 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
    ├── H.P.001-AGENTS/                                   # All H.P.001-AGENTS
    ├── H.P.002-COMMANDS/                                 # All H.P.002-COMMANDS
    ├── H.P.003-SKILLS/                                   # All H.P.003-SKILLS
    └── H.P.004-SCRIPTS/                                  # All H.P.004-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:

1. Master repo contains CODITECT brain
2. Submodules reference via symlink
3. All projects share same component library
4. Updates propagate automatically

---

Core Systems

1. Multi-Agent Orchestration System

Purpose: Coordinate specialized H.P.001-AGENTS for complex H.P.006-WORKFLOWS

Components:

• orchestrator agent - Planning and coordination
• Specialized H.P.001-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:

1. Export session to text or process JSONL
2. Parse messages (user + assistant)
3. Compute SHA-256 hash for each message
4. Compare against global hash pool
5. Store only unique messages
6. 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
• H.P.004-SCRIPTS/session-startup.py - Session initialization

Workflow:

# Activate component
python3 H.P.004-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:

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

---

Integration Patterns

Pattern 1: Agent Coordination

Problem: Complex tasks require multiple H.P.001-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
./H.P.004-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 H.P.009-CONFIG/component-counts.json
• Unique messages deduplicated: 7,500+
• JSONL sessions processed: 100+ MB
• Projects in master repository: 50+

---

Configuration

CODITECT framework H.P.009-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 H.P.004-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 H.P.004-SCRIPTS.core.invoke_agent import invoke_agent
result = invoke_agent(agent_name="orchestrator", task="coordinate deployment")

Orchestrator API

# Coordinate multi-agent workflow
from H.P.004-SCRIPTS.core.orchestrator import coordinate_workflow

result = coordinate_workflow(
    workflow_name="deployment-pipeline",
    phases=["build", "test", "deploy"],
    H.P.001-AGENTS=["devops-engineer", "security-specialist", "codi-qa-specialist"]
)

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

Session Preservation API

# Preserve session context
from H.P.004-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 H.P.004-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