AICodeRally|Documentation

AICodeRally — Unified System Architecture

Version 1.0 · Last Updated: November 28, 2025

Master Reference: UNIFIED_ARCHITECTURE.md in the main repository is the authoritative source for this documentation.

Purpose

AICodeRally is not one product. It's an ecosystem:

This page provides the complete system architecture that governs every technical and operational layer.

System Overview

AICodeRally is built on a dual-core architecture:

      ┌─────────────────────────────────────────┐
      │         AICodeRally Ecosystem           │
      ├─────────────────────────────────────────┤
      │  Rally Stack (Monorepo Factory)         │
      │  – Next.js front-of-house               │
      │  – Python "back-of-house" automation    │
      │  – Rally Modules (plug-in Lego blocks)  │
      ├─────────────────────────────────────────┤
      │  Rally AI (Multi-AI Orchestrator)       │
      │  – Claude (Architect)                   │
      │  – Gemini (Strategist)                  │
      │  – GPT-4/5 (Executor)                   │
      │  – Vercel AI Gateway                    │
      ├─────────────────────────────────────────┤
      │  Agent Protocol                         │
      │  – Claude Code + ChatGPT division       │
      │  – .ai rules & memory system            │
      ├─────────────────────────────────────────┤
      │  Franchise Layers                       │
      │  – Studio / Edge / Summit tiers         │
      │  – Qualification & certification        │
      ├─────────────────────────────────────────┤
      │  Brand System (Racing Sloth Identity)   │
      │  – mascots, palette, traits             │
      └─────────────────────────────────────────┘

The system is modular, predictable, and scalable to hundreds of modules and thousands of franchise installs.

Design Principles

Why This Architecture?

  1. Metadata-First: Modules are defined by metadata contracts, not implementation
  2. TypeScript + Python Split: TypeScript for UI/UX, Python for automation/generation
  3. No Heroic Migrations: Build forward, not backward
  4. AI-Native: Every layer is designed to be AI-readable and AI-modifiable
  5. Franchise-Ready: Can be replicated across 100+ franchise locations

System Constraints & Guarantees

Constraints:

Guarantees:

Rally Stack (Monorepo Factory)

A personal software factory for generating working apps, modules, and prototypes at speed.

Core Philosophy

Folder Structure

rally-stack/
├── apps/
│   ├── studio/                 # Main Next.js UI (Studio tier)
│   ├── edge/                  # SMB app builder (Edge tier)
│   └── summit/                # Enterprise offering (Summit tier)
├── packages/
│   ├── core/                  # Contracts & types
│   ├── ui/                    # Shared UI kit
│   └── modules/               # Real modules (pit-wall, consensus, etc.)
├── tools/
│   ├── rally-ai/             # Multi-AI orchestrator CLI
│   └── python/               # Automation layer
├── .ai/                       # Agent control system
└── docs/                      # Documentation

Module Contract

Every module MUST export this structure:

export const module: RallyModule = {
  meta: {
    id: string,              // kebab-case, unique
    name: string,            // Display name
    description: string,     // Short description
    version: string,         // Semantic versioning
    category: ModuleCategory, // Enum: AI | Data | Tools | etc
    route: string,           // /modules/[id]
  }
}

Why Metadata-First?

Learn More:

Rally AI (Multi-Model Orchestrator)

Rally AI is a CLI that treats AI models like a team.

Model Roles

This triad eliminates blind spots that a single model has.

Commands

# Generate architecture
rally-ai design "feature-name" --context "requirements..."

# Create 4-week build plan
rally-ai sprint-plan "feature-name"

# Security & requirements audit
rally-ai validate "feature-name"

# Multi-agent debate
rally-ai collaborate "feature-name" --rounds 3

# Complete lifecycle in one command
rally-ai workflow "feature-name"

Flow

User → Rally AI → MultiAIOrchestrator → Providers
                              ↓
                     design-docs/
                     sprint-plans/
                     validation/
                     collaborations/

Gateway Integration

The Vercel AI Gateway normalizes:

The orchestrator automatically falls back to SDK mode if gateway is unavailable.

Learn More:

Agent Protocol (.ai Directory)

This is the behavioral OS of the AICodeRally agents.

Files

Agent Roles

Claude Code:

ChatGPT:

Handoff Protocol

  1. ChatGPT builds scaffold
  2. Claude reviews and corrects patterns
  3. ChatGPT implements corrections
  4. Claude approves
  5. Commit & merge

No side-channel divergence allowed.

Learn More:

Module Lifecycle (End-to-End)

Idea → Create → Register → UI → Logic → Validation → Deploy

1. Create

python tools/python/create_module.py id "Name" category

Generates:

2. Register

Auto-injected into packages/modules/index.ts.

3. UI

Built inside: apps/studio/app/modules/[id]/page.tsx

4. Logic

Goes in:

5. Validation

rally-ai validate "module-id"

6. Deployment

Vercel (Next.js) + optional Python host (Fly, Railway).

Learn More:

UX / UI System

Principles

UI Kit

Lives in packages/ui.

Components support:

UX Contract

Every module page must include:

Learn More:

DevOps & Environment

Hosting

Secrets

OIDC Token Refresh

Every 12 hours:

vercel env pull

Local Dev

pnpm dev --filter studio
python tools/python/create_module.py ...

Learn More:

Franchise Layer

AICodeRally is a product + franchise model based on the 3-6-∞ Framework.

The 3-6-∞ Framework

Studio = 3 Steps (Ideate → Create → Validate) Edge = 6 P's (People, Process, Product, Performance, Pipeline, Platform) Summit = ∞ (The 6 P's + Governance, Scale, Integration, Intelligence, Strategy, Change)

Studio – The App Layer (3 Steps)

Goal: Transform ideas into working apps

The Loop: Ideate → Create → Validate

Outputs: Scoping artifacts, prototype apps, business case mini-apps

Edge – The Business Layer (6 P's)

Goal: Turn apps into a Business OS

The 6 Pillars:

Outputs: Edge Solutions (npEdge, bhgEdge, Designer Biz Kit, Brand Hub)

Summit – The Enterprise Layer (∞)

Goal: System-of-systems transformation

Extensions:

Outputs: Summit Solutions, executive dashboards, enterprise orchestration

Franchise Business Model

Studio Tier:

Edge Tier:

Summit Tier:

Learn More:

Business Model (Technical View)

AICodeRally creates multiple revenue streams:

SaaS

Franchise Fees

Module Marketplace

Enterprise

Brand & Identity System

The Sloth Paradox

This contrast is the core brand identity.

Visual Keywords

Learn More:

Glossary

| Term | Definition | |------|------------| | Rally Stack | Monorepo factory | | Rally AI | Multi-AI orchestrator CLI | | Module | Metadata-defined building block | | Agent Protocol | Rules for interacting with AI assistants | | Studio | Franchise offering (one idea → one app) | | Edge | SMB offering (business OS around apps) | | Summit | Enterprise offering (custom, cross-app scale) |

Related Documentation

Application Architecture

Development

Tools & Integration

Deployment & Operations

Business & Brand

Master Reference

This page is derived from the master architecture document:

📄 UNIFIED_ARCHITECTURE.md

The master document in the main repository is the single source of truth. All other documentation must align with it.

When the master document changes → the entire ecosystem documentation changes.

When something isn't defined in the master → it doesn't exist yet.

Final Notes

If it's not in the UNIFIED_ARCHITECTURE.md → it's not core to AICodeRally.

For the complete technical specification with implementation details, architecture deep dives, and code examples, see the master architecture document.