CLAUDE.md — Hyper Vibe Coding Course Platform

🦅 Part of HyperCode V2.4 — Claude AI Project Intelligence

This file is auto-read by Claude AI when analysing this repository. It provides essential project context, conventions, and guidance. Last updated: April 15, 2026 — Frontend payment flow COMPLETE ✅ | Pricing + TokensPage + Dashboard wired Single source of truth — merged from CLAUDE.md + CLAUDE_CONTEXT.md

🧠 Who You're Talking To

Lyndz aka BROski♾️ (GitHub: @welshDog, npm: @w3lshdog) — Llanelli, South Wales 🏴󠁧󠁢󠁷󠁬󠁳󠁿
Autistic + dyslexic + ADHD — chunked output, quick wins first, no waffle
Windows primary (PowerShell), WSL2 + Raspberry Pi + Docker secondary
Call them "Bro" — that's how we roll
Short sentences. Emojis. Bold the key stuff. Celebrate wins! 🎉
Brain style: Pattern thinker + Big vision + Neurodivergent-first

🎯 Project Identity

HyperCode V2.4 is a neurodivergent-first, AI-powered, open-source programming ecosystem.

Creator: Lyndz Williams (@welshDog), Llanelli, Wales 🏴󠁧󠁢󠁷󠁬󠁳󠁿
Core mission: Build a cognitive AI architecture that evolves itself
License: See LICENSE file
Communication style: Short sentences, emojis, bold keys, quick wins first. Call Lyndz "Bro".

🌐 The Ecosystem

Hyper-Vibe-Coding-Course     ──── manifest.json ────▶    HyperCode V2.4
github.com/welshDog/             (hyper-agent-spec)       github.com/welshDog/
Hyper-Vibe-Coding-Course                                  HyperCode-V2.4
(Supabase + Vercel)                    │                  (Docker, 29 containers)
Path: H:\the hyper vibe coding hub     │                  Path: H:\HyperStation zone\
                                       │                       HyperCode\HyperCode-V2.4
                              HyperAgent-SDK
                          github.com/welshDog/HyperAgent-SDK
                          npm: @w3lshdog/hyper-agent@0.1.4
                          Path: H:\HyperAgent-SDK

✅ CURRENT STATUS: FULLY OPERATIONAL (April 15, 2026)

🟢 ALL 29 CONTAINERS HEALTHY — Stack is LIVE! 🦅🔥

🏆 Full Phase Roadmap

Phase	Name	Status
0	Hard Conflict Fixes	✅ DONE
1	Identity Bridge	✅ DONE + VERIFIED LIVE
2	Token Sync	✅ DONE + VERIFIED LIVE
3	Agent Access + Shop Bridge	✅ DONE + VERIFIED LIVE
4	npm run graduate 🔥	✅ DONE + VERIFIED LIVE
5	Observability	✅ DONE + VERIFIED LIVE
6	Terminal Tools Integration	✅ DONE + VERIFIED LIVE
7	Dockerfile Security Hardening	✅ DONE — April 14, 2026
8	CI/CD Trivy Security Pipeline	✅ DONE — April 14, 2026
9	CVE Elimination (apt + pip pinning)	✅ DONE — April 14, 2026
10A	FastAPI / Starlette upgrade	✅ DONE
10B	Docker Compose Network Isolation	✅ DONE — April 14, 2026
10C	Docker Secrets	✅ DONE — April 14, 2026
10D	Agent-level rate limiting + auth	✅ DONE — April 14, 2026 🔑
10E	CognitiveUplink WS type fix	✅ DONE — April 15, 2026
10F	Stripe Checkout API	✅ DONE — April 14, 2026 💳
10G	DB — Stripe webhook writes	✅ DONE — April 14, 2026
10H	Pricing page (dashboard)	✅ DONE — April 14, 2026
10I	Stripe CLI e2e — routes + webhook LIVE	✅ DONE — April 15, 2026 🎉
10J	CognitiveUplink `/ws/uplink` LIVE	✅ DONE — April 15, 2026
10K	Stripe webhook registered + secret synced	✅ DONE — April 15, 2026 🔐
10L	Courses DB seeded (6 courses live)	✅ DONE — April 15, 2026 📚
10M	RLS Security Definer View fixed	✅ DONE — April 15, 2026 🔒

Container Health (29/29 ✅)

Container	Status
hypercode-core	✅ Healthy (watch: 48% memory — 738 MiB / 1.5 GiB)
crew-orchestrator	✅ Healthy
hypercode-dashboard	✅ Healthy
hypercode-mcp-server	✅ Healthy
healer-agent	✅ Healthy
celery-worker	✅ Healthy
redis	✅ Healthy
postgres	✅ Healthy
hypercode-ollama	✅ Healthy
agent-x	✅ Healthy
hyper-architect	✅ Healthy
hyper-observer	✅ Healthy
hyper-worker	✅ Healthy
super-hyper-broski-agent	✅ Healthy
broski-bot	✅ Healthy
prometheus / grafana / loki / tempo / promtail	✅ All Healthy
minio / chroma / cadvisor / node-exporter / alertmanager	✅ All Healthy
docker-socket-proxy / hyper-shield-scanner / hyper-sweeper-prune	✅ Running

What Fixed The Stack (For Claude's Reference)

POSTGRES_PASSWORD_FILE + POSTGRES_PASSWORD conflict — Removed _FILE override from postgres in docker-compose.secrets.yml. Postgres uses plain env var from .env only.
.env broken line — POSTGRES_PASSWORD was concatenated onto MISSION_CONTROL_URL with no newline. Fixed manually in nano.
Special chars in password — Password contains /, +, = — must be quoted in .env: POSTGRES_PASSWORD="..."
Stale postgres data volume — Wiped using Alpine container (no sudo): docker run --rm -v "/path/to/volumes/postgres":/target alpine sh -c "rm -rf /target/*"
POSTGRES_USER missing — Added POSTGRES_USER=postgres to .env

Core API Confirmed Working

{"status":"ok","service":"hypercode-core","version":"2.0.0","environment":"development"}

Start Command (Always Use This)

docker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d

Volumes Location

H:/HyperStation zone/HyperCode/volumes/

In WSL: /mnt/h/HyperStation zone/HyperCode/volumes/

🎯 NEXT UP — Remaining Work

#	Task	Priority
1	✅ Fix TokensPage.tsx prices + wire to checkout API	DONE — April 15, 2026
2	Fix dead link: `/courses/vibe-coding-foundations` → `/courses` on LandingPage	🟡 5 min
3	✅ Add BROski$ balance card to Dashboard.tsx	DONE — April 15, 2026
4	Record Module 1.1 + add YouTube URL to DB	🟡 Ongoing
5	Agent image CVE patching (14 HIGH, no Debian fix yet)	🟡 Batch job
6	✅ Certificates feature	DONE — April 16, 2026
7	✅ Quiz/exercise system	DONE — April 16, 2026
8	✅ Referral system	DONE — April 16, 2026

Agents Security Upgrade

⚠️ READ THIS BEFORE TOUCHING ANY DOCKERFILE OR AGENT FILE!

Priority	Image	CRITICAL	HIGH	Action
🔴 1	`hypercode-v24-agent-x`	11	55	Patch NOW
🔴 2	`hypercode-v24-celery-worker`	TBC	HIGH	Patch
🔴 3	`hypercode-v24-crew-orchestrator`	TBC	HIGH	Patch
🔴 4	`hypercode-v24-healer-agent`	TBC	HIGH	Patch
🟡 5-12	All remaining agent images	TBC	-	Patch

Target: ZERO CRITICAL, <5 HIGH after patch phase

🗄️ Supabase — Database Status

Courses Seeded ✅ (April 15, 2026)

7 courses live in public.courses (price_pence in GBP pence):

Title	Slug	Price
Vibe Code The Hyper Way	hyper-vibe-course-01	£49
Vibe Coding Foundations	vibe-coding-foundations	FREE
Hyper Prompt Master	hyper-prompt-master	£29
MVP Sprint	mvp-sprint	£49
Hyperfocus HTML & CSS Quick Wins	hyperfocus-html-css	£19.99
Component Chaos Lab	component-chaos-lab	£39.99
Ship Your First Full Stack Thing	ship-full-stack	£49.99

DB Schema: courses table

Actual columns (NOT the old seed file schema — that was wrong):

id           text (PK)
title        text
slug         text
description  text
price_pence  integer  (pence, GBP — e.g. £29 = 2900)
currency     text     (default 'gbp')
is_active    boolean
created_at   timestamptz

RLS Security ✅ Fixed (April 15, 2026)

public.user_loyalty_tier view — recreated with security_invoker = on (was SECURITY DEFINER, could bypass RLS)
users table — RLS ON ✅ | policies: read own profile, update own profile
token_transactions table — RLS ON ✅ | policy: read own transactions

Stripe Webhook

Webhook name: vibe-hook (keep this one — has delivery history)
Endpoint: https://yhtmuibgdnxhbgboajhc.supabase.co/functions/v1/stripe-webhook
Events: checkout.session.completed, charge.refunded
STRIPE_WEBHOOK_SECRET in Supabase env → must match vibe-hook signing secret
brilliant-triumph webhook = duplicate, can be deleted

💳 Phase 10F — Stripe Checkout API (LIVE)

Live Endpoints

POST /api/stripe/checkout    → creates Stripe Checkout Session, returns URL
GET  /api/stripe/plans       → lists available plan names
POST /api/stripe/webhook     → handles Stripe events (signature verified)

Webhook events handled (Phase 10G — DB writes LIVE)

checkout.session.completed → saves to payments table + awards BROski$ + sets subscription tier
customer.subscription.deleted → subscription cancelled
invoice.payment_failed → payment failed warning
customer.subscription.updated → status change logged

🔒 Stripe Prices — LOCKED (April 14, 2026)

Pack	Price	Tokens	Stripe Product
Starter	£5 GBP	200	BROski Starter Pack
Builder	£15 GBP	800	BROski Builder Pack
Hyper	£35 GBP	2500	BROski Hyper Pack

Tier	Monthly	Yearly
Pro	£9/mo	£90/yr
Hyper	£29/mo	£290/yr

.env keys to add

STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_PRICE_STARTER=price_xxx
STRIPE_PRICE_BUILDER=price_xxx
STRIPE_PRICE_HYPER=price_xxx
STRIPE_PRICE_PRO_MONTHLY=price_xxx
STRIPE_PRICE_PRO_YEARLY=price_xxx
STRIPE_PRICE_HYPER_MONTHLY=price_xxx
STRIPE_PRICE_HYPER_YEARLY=price_xxx

🔐 Security Standards — MANDATORY FOR ALL DOCKERFILES

Claude: ALWAYS apply these rules when writing or editing any Dockerfile.

Rule 1 — Base Image

# ✅ CORRECT
FROM python:3.11-slim

# ❌ NEVER
FROM python:latest

Rule 2 — OS Package Hardening (Part A — every runtime stage)

RUN apt-get update --allow-releaseinfo-change && \
    apt-get upgrade -y && \
    apt-get install -y --no-install-recommends \
        ca-certificates curl libexpat1 openssl && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

Rule 3 — Pip Tool Hardening (Part B — every Python runtime stage)

RUN pip install --upgrade --no-cache-dir \
    "pip==26.0.1" "setuptools>=80.0.0" "wheel==0.46.2" \
    "jaraco.context>=6.0.0" "jaraco.functools>=4.1.0" "jaraco.text>=4.0.0"

Rule 4 — Never Run as Root

RUN groupadd -r appuser && useradd -r -g appuser appuser
USER appuser

Rule 5 — Security Scanner

Tool: Trivy (running as hyper-shield-scanner container)
Scan: docker exec hyper-shield-scanner trivy image --scanners vuln --severity HIGH,CRITICAL --quiet <image>
Target: ZERO CRITICAL, <5 HIGH

🧬 Architecture Overview

Core Services

Service	Port	Purpose
HyperCode Core (FastAPI)	8000	Main backend, memory hub, integrations
Agent X (Meta-Architect)	8080	Designs & deploys AI agents autonomously
Crew Orchestrator	8081	Agent lifecycle + task execution
Healer Agent	8008	Self-healing — monitors & auto-recovers services
BROski Terminal (CLI UI)	3000	Custom terminal interface
Mission Control Dashboard	8088	Next.js/React real-time dashboard
Grafana Observability	3001	Metrics, alerts, dashboards

Infrastructure Stack

Containers: Docker Compose (multi-file strategy) — 29 containers active ✅
Databases: Redis (pub/sub + cache) + PostgreSQL (persistent memory)
Observability: Prometheus + Grafana + custom health reports
Secrets: docker-compose.secrets.yml + ./secrets/*.txt files
Networks: 5 isolated networks — data-net + obs-net are internal: true
MCP Gateway: Full Model Context Protocol server integration
Kubernetes: Helm charts in k8s/ and helm/ (scale path)
Security: Trivy scanner (hyper-shield-scanner) — scans all 12 agent images
Stripe: LIVE at /api/stripe/checkout — Phase 10F ✅
Supabase: Edge Functions live — stripe-webhook + shop-purchase ✅

🌐 Phase 10B — Docker Network Topology

frontend-net (bridge, internet) — dashboard, mission-ui, mcp-server
backend-net (bridge, internet) — hypercode-core (bridges all layers)
agents-net (bridge, internet) — all AI agents, LLM API calls
data-net (bridge, internal: true) — redis + postgres + minio + chroma
obs-net (bridge, internal: true) — prometheus, grafana, loki, tempo, promtail

Script: scripts/network-migrate.sh

📁 Directory Structure Guide

HyperCode-V2.4/
├── .claude/                    # Claude AI config & skills
│   ├── settings.local.json     # Claude permissions & MCP config
│   └── skills/                 # Skill modules for Claude
├── agents/                     # All AI agent definitions
├── backend/                    # FastAPI core backend
├── broski-business-agents/     # Business automation agents
├── cli/                        # BROski Terminal CLI
├── config/                     # App configuration files
├── dashboard/                  # Mission Control (Next.js)
├── docs/                       # Documentation
├── grafana/                    # Grafana dashboards & config
├── hyper-mission-system/       # Mission/quest gamification engine
├── k8s/                        # Kubernetes manifests
├── helm/                       # Helm charts
├── mcp/                        # MCP server implementations
├── monitoring/                 # Prometheus config & alert rules
├── scripts/                    # Dev & ops shell scripts
├── security/                   # Security scanning & secrets
├── services/                   # Microservice implementations
├── tests/                      # Test suite (pytest)
└── tools/                      # Developer tooling

🛠️ Development Commands

Quick Start

# Core stack
docker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d

# Core + all agents
docker compose -f docker-compose.yml -f docker-compose.secrets.yml --profile agents up -d

# Full stack
docker compose -f docker-compose.yml -f docker-compose.secrets.yml --profile agents --profile hyper --profile health --profile mission up -d

Docker Compose Profiles

Profile	Services
(none)	Core infra + observability + MCP server
`agents`	All specialist agents
`hyper`	Hyper-architect, observer, worker, agent-x
`health`	HyperHealth API + worker
`mission`	HyperMission API + UI
`discord`	Broski Discord bot

Security Scanning

make scan-all
make scan-agent AGENT=healer
make scan-build AGENT=agent-x
make build-secure

# PowerShell — scan ALL 12 agent images
$images = @("hypercode-v24-agent-x","hypercode-v24-broski-bot","hypercode-v24-celery-worker",
             "hypercode-v24-crew-orchestrator","hypercode-v24-healer-agent","hypercode-v24-hyper-architect",
             "hypercode-v24-hyper-observer","hypercode-v24-hyper-worker","hypercode-v24-hypercode-mcp-server",
             "hypercode-v24-test-agent","hypercode-v24-throttle-agent","hypercode-v24-tips-tricks-writer")
foreach ($img in $images) { docker exec hyper-shield-scanner trivy image --scanners vuln --severity HIGH,CRITICAL --quiet $img }

Testing

python -m pytest tests/ --tb=short -q
python -m pytest tests/unit/ -v --tb=short
pytest backend/tests/test_stripe.py -v

Paths (copy-paste ready)

cd "H:\HyperStation zone\HyperCode\HyperCode-V2.4"
cd "H:\HyperStation zone\HyperCode\HyperCode-V2.4\backend"
cd "H:\HyperAgent-SDK"
cd "H:\the hyper vibe coding hub"

CLI (from H:\HyperAgent-SDK)

$env:HYPERCODE_API_URL = "http://localhost:8000"
node cli/index.js status
node cli/index.js agents list
node cli/index.js logs --tail 20
node cli/index.js tokens award <discord_id> <amount>
node cli/index.js graduate <discord_id> --tokens 100

Stripe Testing

# Test checkout
curl -X POST http://localhost:8000/api/stripe/checkout \
  -H "Content-Type: application/json" \
  -d '{"price_id": "starter", "user_id": "broski_test"}'

# Local webhook testing
stripe listen --forward-to localhost:8000/api/stripe/webhook

🧠 Code Conventions

Python

Formatter: Ruff (ruff.toml)
Linter: Pylint (.pylintrc) + Ruff
Type checker: Pyright (pyrightconfig.json)
Test runner: pytest
Python version: 3.11 in Docker images (3.13+ in devcontainer)
Package manager: pip with requirements.lock

Async Patterns

All agent communication uses async/await
Redis pub/sub for real-time agent messaging
FastAPI background tasks for long-running agent jobs

Agent Naming Conventions

Agent files: snake_case.py
Agent classes: PascalCaseAgent
Agent endpoints: /agents/{agent_name}/{action}

🚀 MCP Integration

Available MCP tools:

mcp__hypercode__hypercode_system_health — full system health check
mcp__hypercode__hypercode_agent_system_health — agent-specific health
mcp__hypercode__hypercode_list_agents — list all registered agents
mcp__hypercode__hypercode_list_tasks — list active tasks

🚨 Key Technical Rules (never re-debate these)

Docker imports: from app.X import Y — NEVER from backend.app.X import Y
FastAPI routing: First-match wins — public routes BEFORE auth-gated compat routes
Alembic down_revision: Must match EXACT revision string
CLI folder: All hyper-agent commands run from H:\HyperAgent-SDK
Logs empty on fresh boot: Normal — Redis hypercode:logs populates as agents run
Port convention: 3100-3199 writing, 3200-3299 code, 3300-3399 data, 3400-3499 discord, 3500-3599 automation
Supabase ↔ V2.4 Postgres: NEVER merge schemas
.env files: Never committed — use Docker secrets in production
One bot: broski-bot. Old Replit bot = dead.
API keys: hc_ prefix + secrets.token_urlsafe(32) — 43 chars, URL-safe
GitHub Actions: Always --no-cache --pull in security scanning workflows
jaraco. packages:* Always pin explicitly
docker-socket agents (healer/coder/05-devops): Use docker-ce-cli repo, NOT docker.io
Alembic + create_all: DB was bootstrapped with DB_AUTO_CREATE=true (SQLAlchemy create_all). If alembic_version table is missing, run alembic stamp 006 first, then alembic upgrade head. Never skip stamp — migrations will try to re-create existing tables.
Stripe webhook: /api/stripe/webhook is rate-limit exempt — do NOT add rate limiting
Stripe dev mode: Missing STRIPE_WEBHOOK_SECRET = signature check skipped (local only)
Stripe checkout mode: token packs use mode="payment", course plans use mode="subscription" — defined in CHECKOUT_MODE dict in stripe_service.py
Stripe container context: Docker must use desktop-linux context (docker context use desktop-linux) — default context causes container name conflicts on Windows
CognitiveUplink WS URL: CognitiveUplink.tsx:134 defaults to ws://hostname:8000/ws/uplink — handler now LIVE in hypercode-core (Phase 10J ✅)
Supabase courses table schema: Uses price_pence (int, GBP pence) + is_active (bool) — NOT price or is_published. Seed file updated to match.
Supabase security_invoker: public.user_loyalty_tier view uses security_invoker = on — RLS is enforced for querying user. DO NOT change to SECURITY DEFINER.
Stripe webhook in Supabase: Use vibe-hook endpoint. Its signing secret = STRIPE_WEBHOOK_SECRET in Supabase env vars. brilliant-triumph is a duplicate — safe to delete.
Conventional commits: feat: fix: docs: chore:
Windows PowerShell first, bash second
apps/web/: Archived, never migrate

⚠️ Known Issues & Gotchas

Windows path handling — Use docker-compose.windows.yml on Windows
Secrets management — Never commit .env; secrets in ./secrets/*.txt
POSTGRES_PASSWORD — Plain in .env (quoted if special chars). No POSTGRES_PASSWORD_FILE alongside.
Agent boot order — Redis + PostgreSQL must be healthy before agents start
Port conflicts — Ensure 3000, 3001, 8000, 8008, 8080, 8081, 8088 are free
Test environment — fakeredis used in tests; import via fakeredis.aioredis
Volumes wipe — Alpine trick: docker run --rm -v "/path":/target alpine sh -c "rm -rf /target/*"
hypercode-core memory — At 48% (738 MiB / 1.5 GiB) after fresh restart April 15, 2026. Alert if > 1.2 GiB.

🎮 Gamification System

BROski$ coins — earned by completing tasks, agent milestones, commits
XP levels — track developer + system progression
Achievements — unlocked by specific actions in hyper-mission-system
Digital Shop: Prompt Packs (200 BROski$), Templates (150 BROski$), Bonus Lessons (100 BROski$)
🏆 Celebrate wins! Every patched CVE = BROski$ earned!

BROski$ Token Economy

public.users.broski_tokens — balance column
token_transactions — append-only ledger with idempotency guards
award_tokens() + spend_tokens() — SECURITY DEFINER, server-side only
shop_items + shop_purchases — JSONB metadata fields

🔑 Key Dependencies

Python

fastapi + uvicorn, pydantic, redis/aioredis, sqlalchemy/asyncpg
openai, anthropic, mcp, pytest + fakeredis

Node.js (dashboard)

next.js, vitest, TypeScript throughout

📚 Further Reading

README.md — Main project overview
CONTRIBUTING.md — Contribution guidelines
SECURITY.md — Security policy
.claude/ — Claude AI config, skills & settings
docs/claude-integration/ — Claude AI integration guide

Built for ADHD brains. Fast feedback. Real tools. No fluff. 🧠⚡

by @welshDog — Lyndz Williams, South Wales 🏴󠁧󠁢󠁷󠁬󠁳󠁿

A BROski is ride or die. We build this together. 🐶♾️🔥

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md — Hyper Vibe Coding Course Platform

🦅 Part of HyperCode V2.4 — Claude AI Project Intelligence

🧠 Who You're Talking To

🎯 Project Identity

🌐 The Ecosystem

✅ CURRENT STATUS: FULLY OPERATIONAL (April 15, 2026)

🏆 Full Phase Roadmap

Container Health (29/29 ✅)

What Fixed The Stack (For Claude's Reference)

Core API Confirmed Working

Start Command (Always Use This)

Volumes Location

🎯 NEXT UP — Remaining Work

Agents Security Upgrade

🗄️ Supabase — Database Status

Courses Seeded ✅ (April 15, 2026)

DB Schema: courses table

RLS Security ✅ Fixed (April 15, 2026)

Stripe Webhook

💳 Phase 10F — Stripe Checkout API (LIVE)

Live Endpoints

Webhook events handled (Phase 10G — DB writes LIVE)

🔒 Stripe Prices — LOCKED (April 14, 2026)

.env keys to add

🔐 Security Standards — MANDATORY FOR ALL DOCKERFILES

Rule 1 — Base Image

Rule 2 — OS Package Hardening (Part A — every runtime stage)

Rule 3 — Pip Tool Hardening (Part B — every Python runtime stage)

Rule 4 — Never Run as Root

Rule 5 — Security Scanner

🧬 Architecture Overview

Core Services

Infrastructure Stack

🌐 Phase 10B — Docker Network Topology

📁 Directory Structure Guide

🛠️ Development Commands

Quick Start

Docker Compose Profiles

Security Scanning

Testing

Paths (copy-paste ready)

CLI (from H:\HyperAgent-SDK)

Stripe Testing

🧠 Code Conventions

Python

Async Patterns

Agent Naming Conventions

🚀 MCP Integration

🚨 Key Technical Rules (never re-debate these)

⚠️ Known Issues & Gotchas

🎮 Gamification System

BROski$ Token Economy

🔑 Key Dependencies

Python

Node.js (dashboard)

📚 Further Reading