CODITECT Application Integration

Complete End-to-End System Architecture

Status: Documentation Complete Last Updated: November 23, 2025

📋 Executive Summary

This document explains how the CODITECT application (coditect-core) integrates with the cloud licensing infrastructure (coditect-cloud-infra) to deliver a secure, licensed AI development platform.

Key Points:

CODITECT runs local-first on user's machine (no cloud dependency for core functionality)
Cloud infrastructure provides licensing, session management, and optional collaboration
Integration via License Client SDK with check-on-start pattern
Seamless offline mode with 24-hour grace period
Multi-LLM support (Claude, GPT-4, Gemini, Ollama, LMStudio)

🏗️ System Architecture Overview

High-Level Architecture

🔄 Complete User Journey

1. User Registration & Payment Flow

2. CODITECT Installation & First Run

3. Active Session with Heartbeat

4. Graceful Shutdown

5. Zombie Session Cleanup (Crash/Network Failure)

🔧 CODITECT Application Architecture

Component Breakdown

CODITECT (coditect-core) is a Python application with:

coditect-core/
├── orchestration/              # Core orchestration engine
│   ├── orchestrator.py         # Task orchestration
│   ├── agent_registry.py       # 52 specialized agents
│   ├── command_router.py       # 81 slash commands
│   ├── executor.py             # Task execution
│   └── state_manager.py        # State persistence
│
├── llm_abstractions/           # Multi-LLM support
│   ├── anthropic_llm.py        # Claude integration
│   ├── openai_llm.py           # GPT-4 integration
│   ├── gemini.py               # Gemini integration
│   ├── ollama_llm.py           # Local Ollama
│   ├── lmstudio_llm.py         # Local LMStudio
│   └── llm_factory.py          # Provider factory
│
├── api/                        # Optional REST API mode
│   ├── main.py                 # FastAPI application
│   ├── models.py               # Pydantic models
│   └── auth.py                 # JWT authentication
│
├── agents/                     # 52 specialized agents
│   ├── business-intelligence-analyst/
│   ├── rust-expert-developer/
│   ├── security-specialist/
│   └── ... (49 more agents)
│
├── commands/                   # 81 slash commands
│   ├── new-project.md
│   ├── analyze-hooks.md
│   ├── web-search-hooks.md
│   └── ... (78 more commands)
│
├── skills/                     # 26 production skills
│   ├── git-workflow-automation/
│   ├── code-editor/
│   └── ... (24 more skills)
│
└── scripts/                    # Automation scripts
    ├── coditect-router         # AI command router
    └── ... (20+ scripts)

Execution Modes

1. Local-First Mode (Primary):

# User runs CODITECT locally
cd /path/to/coditect-core
source venv/bin/activate

# CODITECT checks license on startup
python -m orchestration.cli

# License validated → Application starts
# User interacts with 52 agents + 81 commands
# All AI processing happens via user's LLM provider

2. REST API Mode (Optional):

# Run CODITECT as API server
uvicorn api.main:app --host 0.0.0.0 --port 8000

# External applications can call:
POST /api/v1/commands/execute
{
  "command": "/new-project",
  "args": {"description": "Build a CRM system"}
}

# Returns structured results

3. Hybrid Mode:

Local CODITECT installation
Optional cloud sync for session exports
Collaboration features (future)

🔐 License Client SDK Implementation

Architecture

License Client SDK (Python library integrated into CODITECT):

# Example: llm_abstractions/license_client.py

import asyncio
import hashlib
import platform
import requests
from datetime import datetime, timedelta
from threading import Thread
from typing import Optional

class LicenseClient:
    """Client SDK for CODITECT license validation."""

    def __init__(
        self,
        license_api_url: str,
        license_key: str,
        jwt_token: Optional[str] = None,
    ):
        self.api_url = license_api_url
        self.license_key = license_key
        self.jwt_token = jwt_token
        self.session_id: Optional[str] = None
        self.heartbeat_thread: Optional[Thread] = None
        self.running = False
        self.last_success: Optional[datetime] = None

    def get_hardware_id(self) -> str:
        """Generate unique hardware fingerprint."""
        cpu_id = platform.processor()
        mac = self._get_mac_address()
        disk = self._get_disk_serial()

        fingerprint = f"{cpu_id}|{mac}|{disk}"
        return hashlib.sha256(fingerprint.encode()).hexdigest()

    async def acquire_license(self) -> bool:
        """Acquire license on application start."""
        hardware_id = self.get_hardware_id()

        response = await self._post("/api/v1/licenses/acquire", {
            "license_key": self.license_key,
            "hardware_id": hardware_id,
            "jwt_token": self.jwt_token,
        })

        if response.status_code == 200:
            data = response.json()
            self.session_id = data["session_id"]
            self.signed_token = data["signed_token"]

            # Verify signature locally
            if self._verify_signature(self.signed_token):
                # Start heartbeat thread
                self.start_heartbeat()
                return True

        return False

    def start_heartbeat(self):
        """Start background heartbeat thread."""
        self.running = True
        self.heartbeat_thread = Thread(target=self._heartbeat_loop)
        self.heartbeat_thread.daemon = True
        self.heartbeat_thread.start()

    def _heartbeat_loop(self):
        """Send heartbeat every 5 minutes."""
        while self.running:
            try:
                asyncio.sleep(300)  # 5 minutes
                self._send_heartbeat()
            except Exception as e:
                print(f"Heartbeat error: {e}")

    async def _send_heartbeat(self):
        """Send heartbeat to keep session alive."""
        if not self.session_id:
            return

        response = await self._put("/api/v1/licenses/heartbeat", {
            "session_id": self.session_id
        })

        if response.status_code == 200:
            self.last_success = datetime.now()

    async def release_license(self):
        """Release license on shutdown."""
        if not self.session_id:
            return

        # Stop heartbeat
        self.running = False
        if self.heartbeat_thread:
            self.heartbeat_thread.join(timeout=2)

        # Release session
        await self._delete(f"/api/v1/licenses/release", {
            "session_id": self.session_id
        })

        self.session_id = None

Integration Points

1. Application Startup (orchestration/cli.py):

from llm_abstractions.license_client import LicenseClient

async def main():
    # Initialize license client
    license_client = LicenseClient(
        license_api_url="https://license.coditect.ai",
        license_key=os.getenv("CODITECT_LICENSE_KEY"),
        jwt_token=os.getenv("CODITECT_JWT_TOKEN"),
    )

    # Acquire license
    if not await license_client.acquire_license():
        print("Failed to acquire license. Please check your license key.")
        sys.exit(1)

    # Register signal handlers for graceful shutdown
    signal.signal(signal.SIGINT, lambda s, f: shutdown(license_client))
    signal.signal(signal.SIGTERM, lambda s, f: shutdown(license_client))

    # Start CODITECT application
    orchestrator = ProjectOrchestrator()
    orchestrator.run()

2. Graceful Shutdown (orchestration/cli.py):

async def shutdown(license_client: LicenseClient):
    """Handle graceful shutdown."""
    print("Shutting down CODITECT...")

    # Release license
    await license_client.release_license()

    # Cleanup and exit
    sys.exit(0)

📊 Deployment Architecture

Cloud Infrastructure (GCP)

Current Status:

✅ GKE Cluster: coditect-citus-dev (3 nodes, us-central1)
✅ Cloud SQL: PostgreSQL 16 (db-custom-2-7680, 10.67.0.3)
✅ Redis: Memorystore 6GB (10.121.42.67:6378)
✅ Networking: VPC, Cloud NAT, firewall rules
✅ Secret Manager: 9 secrets created

❌ Cloud KMS: Not deployed (Phase 1 blocker)
❌ Identity Platform: Not configured (Phase 1 blocker)
❌ License API: Not deployed (Phase 2 blocker)

Deployment Roadmap:

Phase 1: Security Services (2-3 days)

# 1. Create Cloud KMS module
cd opentofu/modules/kms
tofu init && tofu plan && tofu apply

# 2. Create Identity Platform module
cd opentofu/modules/identity-platform
tofu init && tofu plan && tofu apply

# 3. Verify OAuth flow
curl https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp

Phase 2: License API Backend (5-7 days)

# 1. Create FastAPI project
mkdir coditect-cloud-backend && cd coditect-cloud-backend
pip install fastapi uvicorn sqlalchemy asyncpg redis

# 2. Implement endpoints
# - POST /api/v1/licenses/acquire
# - PUT /api/v1/licenses/heartbeat
# - DELETE /api/v1/licenses/release

# 3. Write tests (80%+ coverage)
pytest tests/ --cov=app --cov-report=html

# 4. Create Dockerfile
docker build -t gcr.io/coditect-citus-prod/license-api:v1 .

Phase 3: Kubernetes Deployment (2-3 days)

# 1. Create Kubernetes manifests
kubectl apply -f kubernetes/license-api-deployment.yaml
kubectl apply -f kubernetes/license-api-service.yaml
kubectl apply -f kubernetes/license-api-ingress.yaml

# 2. Configure SSL/DNS
gcloud compute addresses create license-api-ip --global
gcloud compute ssl-certificates create license-api-cert \
  --domains=license.coditect.ai

# 3. Deploy to GKE
kubectl rollout status deployment/license-api
kubectl get pods -l app=license-api

🎯 Critical Path to Working System

Timeline: 6-7 days with 2 engineers (Backend + DevOps)

Week 1: Phase 1 - Security Services (2-3 days)

Day	Tasks	Owner	Output
1	Create Cloud KMS OpenTofu module	DevOps	KMS key ring + signing key
1-2	Create Identity Platform module	DevOps	OAuth 2.0 endpoints configured
2	Deploy both services to dev environment	DevOps	Test OAuth flow
3	End-to-end OAuth test	Backend	User can authenticate

Success Criteria:

✅ Cloud KMS operational (RSA-4096 signing key)
✅ Identity Platform configured (Google/GitHub OAuth)
✅ Test user can authenticate and get JWT token

Week 1-2: Phase 2 - Backend Development (5-7 days)

Day	Tasks	Owner	Output
1	FastAPI project setup + database models	Backend	SQLAlchemy async models
2	Implement license acquire endpoint	Backend	POST /api/v1/licenses/acquire
2-3	Redis Lua scripts for atomic seat counting	Backend	Lua scripts tested
3	Implement heartbeat endpoint	Backend	PUT /api/v1/licenses/heartbeat
4	Implement release endpoint	Backend	DELETE /api/v1/licenses/release
4-5	Cloud KMS integration (license signing)	Backend	Signed licenses working
5-7	Write comprehensive tests	Backend	80%+ code coverage

Success Criteria:

✅ All 3 endpoints operational
✅ Atomic seat counting via Redis Lua scripts
✅ Cloud KMS signing licenses correctly
✅ 80%+ test coverage

Week 2: Phase 3 - Deployment (2-3 days)

Day	Tasks	Owner	Output
1	Create Dockerfile	DevOps	Multi-stage build optimized
1-2	Write Kubernetes manifests	DevOps	Deployment + Service + Ingress
2	Deploy to GKE	DevOps	License API running in cluster
2-3	Configure SSL/DNS	DevOps	https://license.coditect.ai
3	End-to-end integration test	Both	Full flow working

Success Criteria:

✅ License API deployed to GKE
✅ SSL certificate issued and configured
✅ DNS pointing to load balancer
✅ Complete flow: Register → Acquire → Heartbeat → Release

🔗 Integration with CODITECT Application

Step 1: Implement License Client SDK

File: coditect-core/llm_abstractions/license_client.py

Features:

Hardware fingerprinting (CPU + MAC + Disk)
Check-on-start license validation
Background heartbeat thread (5 min interval)
Graceful shutdown with license release
Offline mode (24-hour grace period)
Local signature verification

Estimated Effort: 1-2 days (14-16 hours)

Step 2: Integrate into CODITECT Startup

File: coditect-core/orchestration/cli.py

Changes:

# Add license check before starting orchestrator
async def main():
    # 1. Initialize license client
    license_client = LicenseClient(...)

    # 2. Acquire license
    if not await license_client.acquire_license():
        handle_license_failure()

    # 3. Start application
    orchestrator = ProjectOrchestrator()
    orchestrator.run()

    # 4. Release license on exit
    await license_client.release_license()

Estimated Effort: 3-4 hours

Step 3: Configure Environment Variables

File: coditect-core/.env.example

# License Configuration
CODITECT_LICENSE_KEY=CODITECT-XXXXXXXXXXXXX
CODITECT_LICENSE_API_URL=https://license.coditect.ai
CODITECT_JWT_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

# LLM Configuration (existing)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Step 4: Update Documentation

Files to update:

coditect-core/README.md - Add license activation instructions
coditect-core/docs/INSTALLATION.md - License configuration steps
coditect-core/docs/TROUBLESHOOTING.md - License error handling

📈 Testing Strategy

Integration Tests

Test Scenarios:

Happy Path:
- User installs CODITECT
- Enters valid license key
- CODITECT starts successfully
- User works for 2 hours
- User closes CODITECT gracefully
- License released immediately
Offline Mode:
- User starts CODITECT (license acquired)
- Network disconnected
- CODITECT continues working (24-hour grace period)
- Network reconnects after 30 minutes
- Heartbeat resumes automatically
Seat Limit:
- User has 1-seat license
- User starts CODITECT on laptop (success)
- User tries to start on desktop simultaneously (failure: seat limit reached)
- User closes laptop
- User can now start on desktop (seat reclaimed)
Crash Recovery:
- User starts CODITECT
- Application crashes (no graceful shutdown)
- Session expires after 6 minutes (TTL)
- User can immediately restart CODITECT on same device
License Expiry:
- User's license expires
- CODITECT blocks startup
- User sees renewal instructions

Load Testing

Scenario: 1,000 concurrent users

# locust_test.py
from locust import HttpUser, task, between

class LicenseAPIUser(HttpUser):
    wait_time = between(1, 3)

    @task
    def acquire_license(self):
        self.client.post("/api/v1/licenses/acquire", json={
            "license_key": "CODITECT-TEST",
            "hardware_id": self.generate_hardware_id(),
        })

    @task(10)  # 10x more frequent than acquire
    def send_heartbeat(self):
        self.client.put("/api/v1/licenses/heartbeat", json={
            "session_id": self.session_id
        })

Target Metrics:

Latency: P50 < 100ms, P95 < 300ms, P99 < 500ms
Throughput: 1,000+ requests/second
Error Rate: < 0.1%

🚀 Go-to-Market Timeline

Beta Launch (Current → December 6, 2025)

Objectives:

Deploy complete licensing system
100 beta testers
Validate licensing flow end-to-end
Collect feedback on user experience

Deliverables:

✅ License API deployed to GKE
✅ License Client SDK integrated into coditect-core
✅ Documentation for beta users
✅ Monitoring and alerting configured

Pilot Launch (December 10, 2025 → February 11, 2026)

Objectives:

500 early adopters
Multi-tier pricing validation
Performance optimization
Feature refinement based on feedback

Deliverables:

✅ Multi-tier license management (Free, Pro, Enterprise)
✅ Payment integration (Stripe)
✅ Self-service license management portal
✅ Comprehensive analytics dashboard

Public Launch (March 11, 2026)

Objectives:

Open to all customers
Marketing campaign launch
Full support infrastructure
Continuous improvement pipeline

🎯 Success Metrics

Metric	Target	Current
License Acquisition Success Rate	> 99%	N/A (not deployed)
Heartbeat Reliability	> 99.9%	N/A
Session Cleanup Accuracy	100%	N/A
Average License API Latency	< 100ms	N/A
License Verification Time	< 2s	N/A
Offline Mode Grace Period	24 hours	N/A
Zombie Session Cleanup Time	< 6 minutes	N/A

📞 Support & Resources

Documentation

README.md - Infrastructure overview
critical-path-analysis.md - Detailed implementation roadmap
gap-analysis.md - Current state vs target state
gcp-infrastructure-inventory.md - Deployed resources

coditect-core - CODITECT application
coditect-cloud-backend - License API (to be created)
coditect-cloud-frontend - Admin dashboard (optional)

Last Updated: November 23, 2025 Infrastructure Status: 35% Complete (Infrastructure deployed, backend pending) Next Milestone: Cloud KMS + Identity Platform deployment (2-3 days) Target MVP: December 6, 2025

📋 Executive Summary​

🏗️ System Architecture Overview​

High-Level Architecture​

🔄 Complete User Journey​

1. User Registration & Payment Flow​

2. CODITECT Installation & First Run​

3. Active Session with Heartbeat​

4. Graceful Shutdown​

5. Zombie Session Cleanup (Crash/Network Failure)​

🔧 CODITECT Application Architecture​

Component Breakdown​

Execution Modes​

🔐 License Client SDK Implementation​

Architecture​

Integration Points​

📊 Deployment Architecture​

Cloud Infrastructure (GCP)​

🎯 Critical Path to Working System​

Week 1: Phase 1 - Security Services (2-3 days)​

Week 1-2: Phase 2 - Backend Development (5-7 days)​

Week 2: Phase 3 - Deployment (2-3 days)​

🔗 Integration with CODITECT Application​

Step 1: Implement License Client SDK​

Step 2: Integrate into CODITECT Startup​

Step 3: Configure Environment Variables​

Step 4: Update Documentation​

📈 Testing Strategy​

Integration Tests​

Load Testing​

🚀 Go-to-Market Timeline​

Beta Launch (Current → December 6, 2025)​

Pilot Launch (December 10, 2025 → February 11, 2026)​

Public Launch (March 11, 2026)​

🎯 Success Metrics​

📞 Support & Resources​

Documentation​

Related Repositories​

📋 Executive Summary

🏗️ System Architecture Overview

High-Level Architecture

🔄 Complete User Journey

1. User Registration & Payment Flow

2. CODITECT Installation & First Run

3. Active Session with Heartbeat

4. Graceful Shutdown

5. Zombie Session Cleanup (Crash/Network Failure)

🔧 CODITECT Application Architecture

Component Breakdown

Execution Modes

🔐 License Client SDK Implementation

Architecture

Integration Points

📊 Deployment Architecture

Cloud Infrastructure (GCP)

🎯 Critical Path to Working System

Week 1: Phase 1 - Security Services (2-3 days)

Week 1-2: Phase 2 - Backend Development (5-7 days)

Week 2: Phase 3 - Deployment (2-3 days)

🔗 Integration with CODITECT Application

Step 1: Implement License Client SDK

Step 2: Integrate into CODITECT Startup

Step 3: Configure Environment Variables

Step 4: Update Documentation

📈 Testing Strategy

Integration Tests

Load Testing

🚀 Go-to-Market Timeline

Beta Launch (Current → December 6, 2025)

Pilot Launch (December 10, 2025 → February 11, 2026)

Public Launch (March 11, 2026)

🎯 Success Metrics

📞 Support & Resources

Documentation

Related Repositories