CODITECT Core Pilot Launch Consolidated Plan

CODITECT-Core Pilot Launch - Consolidated Plan

Document Version: 1.1.0 Status: Active Planning (Security Hardening Added) Created: December 17, 2025 Updated: December 22, 2025 Owner: Hal Casteel, Founder/CEO/CTO, AZ1.AI INC. Target Launch: December 24, 2025 (Pilot Phase 1)

⚠️ Conformance Gap Alert (Dec 22, 2025)

Security Conformance Score: 42/100 (F grade) Action: Added Phase 2.5 Security Hardening (8-12 hours) Reference: E008-SECURITY-COMPLIANCE epic for full enterprise security

Executive Summary

This consolidated plan unifies all existing plans for the first external (non-internal) CODITECT-Core pilot deployment. This is a PAID PILOT requiring integrated payment processing, license management, and local deployment infrastructure.

Scope

Component	Description	Status
License Server	User registration, license validation, feature gating	Planning
Stripe Integration	Paid subscriptions, checkout, billing portal	Planning
Local Deployment	Single-user CLI/framework installation	Ready
Packaging	npm distribution, 21 packages across 6 platforms	Ready

Critical Path Timeline

TODAY (Dec 17) ────────────────────────────────> PILOT LAUNCH (Dec 24)
     │                                                    │
     │  Week 1 (Dec 17-23): Server Infrastructure        │
     │  ├── License Server MVP                           │
     │  ├── Stripe Basic Integration                     │
     │  ├── Registration Flow                            │
     │  └── Local CLI with License Validation            │
     │                                                    │
     └────────────────────────────────────────────────────┘
                         7 DAYS

Part 1: Server-Side Infrastructure

1.1 License Server (api.coditect.ai)

Source Documentation:

docs/03-architecture/licensing/LICENSING-STRATEGY-PILOT-PHASE.md
docs/03-architecture/licensing/CODITECT-LICENSE-MANAGEMENT-STRATEGY.md

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  api.coditect.ai (GCP)                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Cloud Run Service (FastAPI)                               │
│  ├─ POST /api/v1/auth/signup      - User registration      │
│  ├─ POST /api/v1/auth/login       - User authentication    │
│  ├─ POST /api/v1/licenses/validate - License validation    │
│  ├─ POST /api/v1/licenses/activate - License activation    │
│  ├─ GET  /api/v1/licenses/features - Feature entitlements  │
│  └─ POST /api/v1/billing/checkout  - Stripe checkout       │
│                                                             │
│  Cloud SQL (PostgreSQL)                                    │
│  ├─ organizations                                          │
│  ├─ users                                                   │
│  ├─ licenses                                               │
│  ├─ activations                                            │
│  └─ subscriptions (Stripe sync)                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

MVP Endpoints (Pilot Phase 1)

Endpoint	Method	Purpose	Priority
`/auth/signup`	POST	New user registration	P0
`/auth/login`	POST	User authentication (JWT)	P0
`/licenses/validate`	POST	Validate license key + hardware	P0
`/licenses/activate`	POST	Activate license on device	P0
`/billing/checkout`	POST	Create Stripe checkout session	P0
`/billing/portal`	POST	Create Stripe billing portal	P1
`/licenses/features`	GET	Get feature entitlements	P1

Database Schema (MVP)

-- Organizations (customer companies)
CREATE TABLE organizations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    stripe_customer_id VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Users
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    organization_id UUID REFERENCES organizations(id),
    role VARCHAR(50) DEFAULT 'member',
    created_at TIMESTAMP DEFAULT NOW()
);

-- Licenses
CREATE TABLE licenses (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    license_key VARCHAR(50) UNIQUE NOT NULL,
    organization_id UUID REFERENCES organizations(id),
    tier VARCHAR(50) NOT NULL,  -- pilot, starter, professional
    status VARCHAR(50) DEFAULT 'active',
    expires_at TIMESTAMP NOT NULL,
    max_activations INT DEFAULT 1,
    features JSONB DEFAULT '{}',
    stripe_subscription_id VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Activations (device tracking)
CREATE TABLE activations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    license_id UUID REFERENCES licenses(id),
    hardware_id VARCHAR(64) NOT NULL,
    machine_name VARCHAR(255),
    last_validated_at TIMESTAMP DEFAULT NOW(),
    status VARCHAR(50) DEFAULT 'active',
    UNIQUE(license_id, hardware_id)
);

1.2 Stripe Integration (Paid Pilot)

Source Documentation:

submodules/integrations/Stripe/docs/project-plan.md
submodules/integrations/Stripe/docs/SDD-SOFTWARE-DESIGN-DOCUMENT.md

Pilot Pricing Tiers

Tier	Monthly	Annual	Features
Pilot Starter	$19	$190	3 projects, 100 AI requests, 1 device
Pilot Professional	$49	$490	Unlimited projects, 1000 AI requests, 3 devices

MVP Integration Points

Checkout Session - User signup → Stripe Checkout → License creation
Webhook Handler - checkout.session.completed → Create license
Billing Portal - Self-service payment management
Subscription Sync - Keep license status synced with Stripe

Stripe Setup Checklist (Pre-Launch)

□ Stripe Account
  □ Create account (if not exists)
  □ Complete business verification
  □ Configure branding (logo, colors)

□ Products & Prices
  □ Create "CODITECT Pilot Starter" product
  □ Create "CODITECT Pilot Professional" product
  □ Configure monthly and annual prices
  □ Set up trial period (optional: 7 days)

□ Webhook Configuration
  □ Add endpoint: https://api.coditect.ai/webhooks/stripe
  □ Subscribe to events:
    - checkout.session.completed
    - customer.subscription.updated
    - customer.subscription.deleted
    - invoice.paid
    - invoice.payment_failed
  □ Copy webhook signing secret

□ Customer Portal
  □ Enable subscription management
  □ Enable payment method updates
  □ Configure product switching

□ API Keys
  □ Copy live API keys
  □ Copy test API keys
  □ Store in Secret Manager

Part 2: Local Deployment Architecture

2.1 CLI Installation Flow

Source Documentation:

docs/07-deployment/NPM-PUBLISHING-GUIDE.md
docs/07-deployment/PILOT-INSTALLATION-GUIDE.md

User Journey

1. USER VISITS WEBSITE
   └── https://coditect.ai/signup

2. SIGNUP & PAYMENT
   └── Enter email, password, select plan
   └── Stripe Checkout (credit card)
   └── Account created + License generated

3. RECEIVE LICENSE KEY
   └── Email with license key
   └── Format: CODITECT-PILOT-XXXX-YYYY-ZZZZ

4. INSTALL CLI
   └── npm install -g @coditect-ai/coditect-core
   └── (optionalDependencies auto-select platform)

5. ACTIVATE LICENSE
   └── coditect activate CODITECT-PILOT-XXXX-YYYY-ZZZZ
   └── Hardware fingerprint registered
   └── Features unlocked

6. START USING
   └── coditect init .
   └── coditect status

npm Package Architecture

@coditect-ai/
├── coditect-core              # Main package (auto-selects platform)
├── coditect-core-darwin-arm64 # macOS Apple Silicon
├── coditect-core-darwin-x64   # macOS Intel
├── coditect-core-linux-x64    # Linux x64
├── coditect-core-linux-arm64  # Linux ARM64
├── coditect-core-linux-musl   # Alpine Linux
└── coditect-core-win32-x64    # Windows x64

2.2 License Validation in CLI

# On CLI startup (simplified flow)
def validate_license():
    # 1. Check local license.json
    local_license = load_local_license()

    # 2. Validate offline (if within grace period)
    if local_license and local_license.valid_until > now():
        return local_license

    # 3. Online validation
    response = api.post("/licenses/validate", {
        "license_key": local_license.key,
        "hardware_id": get_hardware_fingerprint(),
        "version": CODITECT_VERSION
    })

    # 4. Store updated validation
    if response.valid:
        save_local_license(response.license)
        return response.license

    # 5. License invalid - show upgrade prompt
    raise LicenseInvalidError(response.message)

Part 3: Implementation Tasks

Phase 0: Pre-Launch Setup (Dec 17-18)

Stripe Configuration

0.1 Create Stripe products and prices
0.2 Configure webhook endpoint
0.3 Set up Customer Portal
0.4 Store API keys in GCP Secret Manager
0.5 Test with Stripe CLI locally

GCP Infrastructure

0.6 Create Cloud SQL PostgreSQL instance
0.7 Create Cloud Run service (api.coditect.ai)
0.8 Configure VPC connector
0.9 Set up DNS (api.coditect.ai)
0.10 Configure SSL certificate

Phase 1: License Server MVP (Dec 18-20) ✅ COMPLETE

Authentication

1.1 Implement /auth/signup endpoint ✅
1.2 Implement /auth/login endpoint (JWT) ✅
1.3 Implement password hashing (Argon2) ✅
1.4 Implement JWT token generation/validation ✅

License Management

1.5 Implement license key generation ✅
1.6 Implement /licenses/validate endpoint ✅
1.7 Implement /licenses/activate endpoint ✅
1.8 Implement hardware fingerprint validation ✅
1.9 Implement activation limits ✅

Stripe Integration

1.10 Implement /billing/checkout endpoint ✅
1.11 Implement Stripe webhook handler ✅
1.12 Handle checkout.session.completed ✅
1.13 Auto-create license on payment success ✅
1.14 Implement /billing/portal endpoint ✅

OAuth Integration (Added Dec 19)

1.15 Implement OAuth callback endpoint ✅
1.16 Google OAuth provider support ✅
1.17 GitHub OAuth provider support ✅
1.18 CLI OAuth login/logout commands ✅

Phase 2: CLI License Integration (Dec 20-22)

License Validation

2.1 Add license validation on CLI startup ✅
2.2 Implement hardware fingerprint generation ✅
2.3 Implement coditect activate command ✅
2.4 Implement coditect license status command ✅
2.5 Implement offline grace period (72 hours) ✅

Error Handling

2.6 Graceful degradation when offline ✅
2.7 Clear error messages for license issues ✅
2.8 Upgrade prompts for expired licenses

Phase 2.5: Security Hardening (Dec 21-22) 🔒 NEW

Source: Conformance Analysis - Security Score 42/100 (F grade) Estimated Time: 8-12 hours

P0 - MUST Have Before Launch (Blocking)

P1 - Should Have Before Launch

2.5.4 Add audit logging table and middleware
- Log: signup, login, logout, failed_login, activate, validate
2.5.5 Harden input validation (max lengths)
2.5.6 Verify Stripe webhook signature enforcement
2.5.7 Harden error responses (no info leakage)

Phase 3: Testing & Verification (Dec 22-23)

Integration Testing

3.1 Test full signup → payment → activation flow
3.2 Test license validation on multiple platforms
3.3 Test Stripe webhook reliability
3.4 Test offline grace period
3.5 Test activation limits

Security Testing (NEW)

3.6 Test rate limiting (verify 429 responses)
3.7 Test failed login lockout (5 attempts → lock)
3.8 Test security headers present in responses
3.9 Verify audit logs capturing events

Platform Testing

3.10 Test on macOS (Intel + ARM)
3.11 Test on Linux (x64)
3.12 Test on Windows
3.13 Verify npm installation on all platforms

Phase 4: Launch (Dec 24)

Pre-Launch Checklist

4.1 Final Stripe configuration review
4.2 Production API keys configured
4.3 Monitoring and alerting enabled
4.4 Support email configured
4.5 User documentation ready

Launch

4.6 Enable production signup
4.7 Send invites to pilot users (50-100)
4.8 Monitor first signups
4.9 Be available for support

Part 4: Pilot User Experience

Registration Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. LANDING PAGE (coditect.ai)                              │
│    └── "Start Your Pilot" button                           │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. SIGNUP FORM                                              │
│    ├── Email                                                │
│    ├── Password                                             │
│    ├── Company Name                                         │
│    └── Plan Selection (Starter $19/mo, Pro $49/mo)         │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. STRIPE CHECKOUT                                          │
│    ├── Credit card entry (Stripe hosted)                   │
│    ├── Process payment                                      │
│    └── Redirect to success page                             │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. SUCCESS PAGE                                             │
│    ├── "Welcome to CODITECT!"                              │
│    ├── License Key: CODITECT-PILOT-XXXX-YYYY-ZZZZ          │
│    └── Installation instructions                            │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. EMAIL CONFIRMATION                                       │
│    ├── License key                                          │
│    ├── Installation guide link                              │
│    └── Support contact                                       │
└─────────────────────────────────────────────────────────────┘

CLI Experience

# Step 1: Install
$ npm install -g @coditect-ai/coditect-core
✓ Installed coditect-core v1.0.0

# Step 2: Activate
$ coditect activate
Enter your license key: CODITECT-PILOT-XXXX-YYYY-ZZZZ
✓ License validated
✓ Device registered (MacBook Pro - hal@az1.ai)
✓ CODITECT activated successfully!

# Step 3: Verify
$ coditect license status
╭─────────────────────────────────────────╮
│ CODITECT License Status                 │
├─────────────────────────────────────────┤
│ Plan:        Pilot Professional         │
│ User:        hal@az1.ai                 │
│ Expires:     March 24, 2026             │
│ Devices:     1/3 activated              │
│ Status:      ✓ Active                   │
╰─────────────────────────────────────────╯

# Step 4: Use
$ coditect init .
✓ CODITECT initialized

Part 5: Success Metrics

Pilot Phase 1 (Dec 24 - Jan 21)

Metric	Target	Measurement
Paid Signups	50-100 users	Stripe dashboard
Activation Rate	>80%	License activations / signups
Payment Success	>95%	Stripe metrics
Support Tickets	<20% of users	Support system
NPS Score	>40	User survey

Revenue Targets

Period	Target MRR	Calculation
Month 1	$2,000	50 users × $40 avg
Month 3	$5,000	100 users × $50 avg
Month 6	$15,000	300 users × $50 avg
Month 12	$150,000	3,000 users × $50 avg

Part 6: Risk Mitigation

Technical Risks

Risk	Probability	Impact	Mitigation
License server downtime	Medium	High	72-hour offline grace period
Stripe API issues	Low	High	Retry logic, error handling
Platform compatibility	Medium	Medium	Extensive testing, fallback options

Business Risks

Risk	Probability	Impact	Mitigation
Low conversion	Medium	High	Clear value proposition, trial option
Churn	Medium	Medium	Onboarding optimization, support
Key sharing	Low	Low	Hardware fingerprinting, activation limits

Appendix A: Source Documents

Document	Location	Purpose
Master PROJECT-PLAN	`/docs/project-management/project-plan.md`	Overall timeline
License Strategy	`/docs/03-architecture/licensing/LICENSING-STRATEGY-PILOT-PHASE.md`	License system design
License Management	`/docs/03-architecture/licensing/CODITECT-LICENSE-MANAGEMENT-STRATEGY.md`	Multi-product strategy
Stripe PROJECT-PLAN	`/submodules/integrations/Stripe/docs/project-plan.md`	Payment integration
Stripe SDD	`/submodules/integrations/Stripe/docs/SDD-SOFTWARE-DESIGN-DOCUMENT.md`	Technical design
npm Publishing	`/docs/07-deployment/NPM-PUBLISHING-GUIDE.md`	Package distribution
Pilot Installation	`/docs/07-deployment/PILOT-INSTALLATION-GUIDE.md`	User installation guide

Appendix B: Quick Reference

API Endpoints Summary

POST /api/v1/auth/signup         # Create account
POST /api/v1/auth/login          # Get JWT token
POST /api/v1/licenses/validate   # Validate license + hardware
POST /api/v1/licenses/activate   # Activate on device
POST /api/v1/billing/checkout    # Stripe checkout session
POST /api/v1/billing/portal      # Stripe billing portal
POST /webhooks/stripe            # Stripe webhook handler

Environment Variables

# Database
DATABASE_URL=postgresql://...

# Stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_STARTER_MONTHLY=price_...
STRIPE_PRICE_PRO_MONTHLY=price_...

# Auth
JWT_SECRET=...
JWT_EXPIRY=24h

# Feature Flags
ENABLE_PILOT_SIGNUP=true
PILOT_USERS_LIMIT=100

Document Control:

Created: December 17, 2025
Author: CODITECT Engineering Team
Review: Before pilot launch (Dec 23)
Next Update: Post-launch review (Dec 31)

⚠️ Conformance Gap Alert (Dec 22, 2025)​

Executive Summary​

Scope​

Critical Path Timeline​

Part 1: Server-Side Infrastructure​

1.1 License Server (api.coditect.ai)​

Architecture​

MVP Endpoints (Pilot Phase 1)​

Database Schema (MVP)​

1.2 Stripe Integration (Paid Pilot)​

Pilot Pricing Tiers​

MVP Integration Points​

Stripe Setup Checklist (Pre-Launch)​

Part 2: Local Deployment Architecture​

2.1 CLI Installation Flow​

User Journey​

npm Package Architecture​

2.2 License Validation in CLI​

Part 3: Implementation Tasks​

Phase 0: Pre-Launch Setup (Dec 17-18)​

Stripe Configuration​

GCP Infrastructure​

Phase 1: License Server MVP (Dec 18-20) ✅ COMPLETE​

Authentication​

License Management​

Stripe Integration​

OAuth Integration (Added Dec 19)​

Phase 2: CLI License Integration (Dec 20-22)​

License Validation​

Error Handling​

Phase 2.5: Security Hardening (Dec 21-22) 🔒 NEW​

P0 - MUST Have Before Launch (Blocking)​

P1 - Should Have Before Launch​

Phase 3: Testing & Verification (Dec 22-23)​

Integration Testing​

Security Testing (NEW)​

Platform Testing​

Phase 4: Launch (Dec 24)​

Pre-Launch Checklist​

Launch​

Part 4: Pilot User Experience​

Registration Flow​

CLI Experience​

Part 5: Success Metrics​

Pilot Phase 1 (Dec 24 - Jan 21)​

Revenue Targets​

Part 6: Risk Mitigation​

Technical Risks​

Business Risks​

Appendix A: Source Documents​

Appendix B: Quick Reference​

API Endpoints Summary​

Environment Variables​

⚠️ Conformance Gap Alert (Dec 22, 2025)

Executive Summary

Scope

Critical Path Timeline

Part 1: Server-Side Infrastructure

1.1 License Server (api.coditect.ai)

Architecture

MVP Endpoints (Pilot Phase 1)

Database Schema (MVP)

1.2 Stripe Integration (Paid Pilot)

Pilot Pricing Tiers

MVP Integration Points

Stripe Setup Checklist (Pre-Launch)

Part 2: Local Deployment Architecture

2.1 CLI Installation Flow

User Journey

npm Package Architecture

2.2 License Validation in CLI

Part 3: Implementation Tasks

Phase 0: Pre-Launch Setup (Dec 17-18)

Stripe Configuration

GCP Infrastructure

Phase 1: License Server MVP (Dec 18-20) ✅ COMPLETE

Authentication

License Management

Stripe Integration

OAuth Integration (Added Dec 19)

Phase 2: CLI License Integration (Dec 20-22)

License Validation

Error Handling

Phase 2.5: Security Hardening (Dec 21-22) 🔒 NEW

P0 - MUST Have Before Launch (Blocking)

P1 - Should Have Before Launch

Phase 3: Testing & Verification (Dec 22-23)

Integration Testing

Security Testing (NEW)

Platform Testing

Phase 4: Launch (Dec 24)

Pre-Launch Checklist

Launch

Part 4: Pilot User Experience

Registration Flow

CLI Experience

Part 5: Success Metrics

Pilot Phase 1 (Dec 24 - Jan 21)

Revenue Targets

Part 6: Risk Mitigation

Technical Risks

Business Risks

Appendix A: Source Documents

Appendix B: Quick Reference

API Endpoints Summary

Environment Variables