ComputerConnection/cc-platform-context

Computer Connection Platform v3 Context

This skill provides comprehensive context for Claude Code sessions working on the CC Platform — the AI infrastructure and business operations platform for Computer Connection, a full-service computer hardware company in Oklahoma City. Intel Gold member, PNY authorized partner, Intel Gaming Council member, and recognized system integrator with ASI distributor access. Custom PCs, components, peripherals, accessories, and full-service repair. Likely the biggest computer shop in OKC.

Repo Map — Three Repositories

| Repo | Path | What It Is | |------|------|-----------| | cc-platform | /home/zach-linux/repos/cc-platform/ | Submodule monorepo — internal operations + dual-purpose infrastructure (agents, MCP servers, infrastructure, knowledge, v3 micro-apps, Flask tools) | | cc-product | /home/zach-linux/repos/cc-product/ | CC-OS — the standalone customer product. Private AI assistant that ships on every hardware system. "Your AI. Your Building. Your Rules." Next.js 16 + Ollama + PostgreSQL/pgvector. 4 hardware tiers (Starter/Pro/Business/Enterprise). | | cc-autoresearch | /home/zach-linux/repos/cc-autoresearch/ | Research automation tooling |

CC-OS is the base layer every customer gets. The v3 micro-apps in cc-platform are SaaS add-ons layered on top. See cc-platform/PLATFORM.md for the full internal-vs-customer breakdown.

Platform Overview

Location: /home/zach-linux/repos/cc-platform/dashboards/v3/ Stack: Next.js 16 · React 19 · TypeScript 5.7 · Tailwind CSS 4 · Drizzle ORM · PostgreSQL 15 · Redis (Valkey 8) · pnpm 10.17

The platform consists of:

• 15 applications in apps/ (12 micro-apps + 1 full-stack dashboard + 1 WebSocket service + 1 Tauri desktop app)
• 8 shared packages in packages/
• Event-driven architecture via Redis Streams for cross-app communication

---

Apps

The Main App: apps/web

This is the most important component in the monorepo — a full-stack Next.js 16 dashboard with 1,000+ files and 166+ API routes spanning 10 business domains (intake, quotes, builds, POS, inventory, dispatch, CRM, scheduling, service, admin). It has the only meaningful test coverage in the project.

| Detail | Value | |--------|-------| | Port | 3000 | | State | Redux Toolkit + SWR | | Auth | next-auth 5.0 beta, authorize('resource:action') pattern | | Payments | Stripe 20.x | | Comms | Twilio (SMS), Nodemailer (email) | | Tests | Vitest (unit + integration), Playwright (E2E), Storybook | | PDF | pdfkit + qrcode |

Directory structure:

apps/web/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Login, registration
│   ├── (dashboard)/       # Main dashboard pages
│   ├── api/               # 166+ API route handlers
│   ├── components/        # React components
│   ├── modules/           # Feature modules (workflow-editor, smart-intake)
│   └── portal/            # Customer-facing portal (quotes, builds, work orders)
├── lib/                   # Utilities, hooks, store (Redux)
├── server/                # Server-side domain logic
│   └── domains/           # DDD service layer
├── tests/                 # Unit + integration tests
├── e2e/                   # Playwright E2E tests
└── .storybook/            # Component documentation

Micro-Apps (12)

Each is an independent Next.js 16 app with its own API routes, state (Zustand), and domain logic. All use standalone output mode for containerization. Dark theme by default.

| App | Port | Purpose | |-----|------|---------| | cc-portal | 3100 | Staff hub, navigation shell, auth middleware, search | | cc-intake | 3101 | Customer check-in, smart intake forms with conditional question trees | | cc-quote | 3102 | Quote generation, cost estimation, variant management | | cc-builder | 3103 | Build tracking, PC configuration, assembly workflow | | cc-dispatch | 3104 | Ticket triage, SLA tracking, technician assignment | | cc-crm | 3105 | Customer management, warranties, follow-ups | | cc-schedule | 3106 | Appointment calendar, availability, blocked time | | cc-inventory | 3107 | Stock levels, procurement, RMA, cycle counts (largest micro-app: 138 files) | | cc-pos | 3108 | Point of sale, checkout, gift cards, discounts | | cc-service | 3109 | Work orders, service templates, labor tracking | | cc-admin | 3110 | User management, settings, audit logs | | cc-supply | 3112 | Supplier management, purchase orders, procurement |

Micro-app directory structure (no src/ wrapper):

apps/cc-{name}/
├── app/                    # Next.js App Router
│   ├── api/               # API routes (/api/*)
│   ├── (layout)/          # Route groups with layouts
│   └── page.tsx           # Pages
├── lib/                   # Utilities, hooks, config
│   └── hooks/             # React hooks
├── server/                # Server-side logic
├── next.config.ts         # Standalone output, transpile packages
├── tailwind.config.ts     # Extends @cc/ui preset
└── tsconfig.json          # Extends root tsconfig.base.json

Infrastructure Apps

| App | Type | Port | Purpose | |-----|------|------|---------| | realtime | Node.js WebSocket | 4001 | Live updates via Redis pub/sub, channel management, presence tracking, message recovery | | desktop | Tauri 2.x | — | Native desktop app with offline queue, kiosk mode, role-based UI (Zustand + React Router) |

---

Shared Packages

All packages live in packages/ and are referenced as @cc/{name} workspace dependencies. The dependency graph is clean — most have zero internal cross-dependencies.

| Package | Purpose | Key Details | |---------|---------|-------------| | @cc/db | Database layer | Drizzle ORM 0.38, PostgreSQL via pg, raw SQL migrations in migrations/, connection pooling, query analysis, transactions | | @cc/auth | Authentication | JWT creation/verification, RBAC with authorize('resource:action'), withRateLimit(), multi-tenancy, session management | | @cc/ui | Component library | 35+ Radix UI primitives, Tailwind preset with semantic design tokens, dark mode, skeletons, empty states | | @cc/schemas | Validation | Zod schemas for customer, inventory, procurement, POS, service domains | | @cc/events | Event bus | Redis Streams, 34 event types, dead letter queue, consumer groups | | @cc/api-client | HTTP client | Circuit breaker, retry with backoff, service discovery, correlation IDs | | @cc/pdf | PDF generation | 9 generators: invoices, quotes, work orders, receipts, labels, etc. | | @cc/monitoring | Observability | Health checks (/api/health/live, /api/health/ready), structured JSON logger, Prometheus metrics |

Cross-Package Dependencies

Only two cross-links exist:

• @cc/api-client → @cc/auth (for auth headers)
• @cc/monitoring → @cc/db (for health checks)

Everything else is independent.

---

Key Architectural Patterns

Pattern 1: API Route → authorize → query → respond

Every API route in the web app follows this pattern:

export async function GET(request: NextRequest) {
  const auth = await authorize('quotes:read');
  if (!auth.authorized) return auth.response;

  try {
    const data = await pool.query('SELECT * FROM quotes WHERE ...');
    return NextResponse.json({ data: data.rows });
  } catch (error) {
    console.error('[quotes/GET]', error);
    return NextResponse.json({ error: 'Failed to fetch' }, { status: 500 });
  }
}

The authorize() call appears 375+ times across the web app. Micro-apps are inconsistent — some use it, some skip auth entirely (known issue).

Pattern 2: Event-Driven Communication

Apps communicate asynchronously via Redis Streams. 34 event types are defined in @cc/events/src/schemas.ts:

Event domains (dot-separated naming):

• intake.* — session_created, customer_created, repair_intent, lead_qualified
• quote.* — created, sent, approved, rejected
• ticket.* — created, assigned, status_changed, completed
• build.* — config_created, config_ready, parts_list
• supply.* — stock_low, po_created, received, cost_changed, availability_check
• customer.* — updated, tagged, inactive_alert
• appointment.* — scheduled, cancelled, reminder_due
• comms.* — message_sent, message_received
• pulse.* — campaign_sent, engagement_score_updated
• ops.* — queue_optimization, utilization_alert
• evolve.* — recommendation_created, recommendation_approved

Pattern 3: Standardized Responses

Via @cc/api-client/src/responses.ts:

// Success
{ data: T, meta?: { total, page, limit, totalPages } }

// Error
{ error: { code: string, message: string, details?: any } }

Pattern 4: Drizzle ORM + Raw SQL

Database access uses Drizzle ORM with PostgreSQL. Migrations are raw SQL files:

// packages/db/src/client.ts — connection pool
import { Pool } from 'pg';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

// Typical query pattern in API routes
const result = await pool.query(
  'SELECT * FROM customers WHERE id = $1',
  [customerId]
);

Migrations live in packages/db/migrations/ as numbered SQL files:

001_initial_schema.sql
002_pos_and_appointments.sql
003_inventory.sql
004_work_orders.sql
...029+

Pattern 5: Service Discovery & Resilience

@cc/api-client provides circuit breaker, retry, and service discovery:

const quote = await apiClient.get(
  'cc-quote',                    // Service name
  `/api/quotes/${id}`,           // Path (no /v1/ prefix)
  { schema: QuoteSchema }        // Zod validation
);

---

Infrastructure (Docker Compose)

Running on a RackChoice 5U (Threadripper 3960X, ASUS ROG Strix TRX40, 128GB DDR4, dual RTX 3090 EVGA XC3 48GB VRAM total, 2TB NVMe, Seasonic 1600W, Arctic 360 Silent Loop), accessed via Tailscale at 100.92.129.93.

| Service | Version | Purpose | |---------|---------|---------| | PostgreSQL | 15-alpine | Primary database, extensions: uuid-ossp, pg_trgm | | Valkey | 8 | Redis-compatible cache, event streams | | Ollama | Latest | Local LLM inference (optional) | | Traefik | v3.6 | Reverse proxy, *.cc.local routing | | dnsmasq | Latest | Local DNS for *.cc.local domains | | Prometheus | Latest | Metrics collection | | Grafana | Latest | Metrics visualization | | Mosquitto | Latest | MQTT for IoT devices |

Networks: cc-internal (inter-service), cc-proxy (Traefik routing), cc-data (database tier)

---

Database Schema (30+ Tables)

Core: customers, devices, tickets, quotes, work_orders, builds Sales: orders, order_items, payments Inventory: parts, bin_locations, stock_movements, inventory_reservations Service: warranty_plans, warranty_subscriptions, warranty_claims Admin: users, roles, audit_logs, settings

Key facts:

• customers.email is nullable (despite being used as identifier in some flows)
• 29+ migration files, but migration numbers 007 and 008 each have duplicates
• work_orders has generated columns that conflict with triggers

---

Testing

Reality Check

Only apps/web has meaningful test coverage (~118 tests). 22 of 24 apps/packages have zero tests. The shared packages (@cc/db, @cc/auth, @cc/events, etc.) are all untested.

Available Commands

# From apps/web
pnpm test                    # Vitest unit tests
pnpm test:unit               # Unit tests only
pnpm test:integration        # Integration tests (VITEST_INTEGRATION=1)
pnpm test:smart-intake       # Module-specific tests
pnpm test:coverage           # Coverage reports
pnpm test:e2e                # Playwright E2E

# From root (turbo)
pnpm test:contracts          # API contract tests
pnpm test:e2e-flows          # Full workflow tests
pnpm test:benchmarks         # Performance benchmarks

CI/CD

GitHub Actions CI in .github/workflows/ci.yml. Note: continue-on-error: true on PR test jobs means broken code can merge. Staging deployment pipeline in deploy-staging.yml has placeholder echo statements instead of actual deployment.

---

Monitoring & Observability

Health Checks

Apps expose two endpoints:

GET /api/health/live   → { status: "ok", timestamp: "..." }
GET /api/health/ready  → { status: "ready", checks: { database: "ok", redis: "ok" } }

Structured Logging

@cc/monitoring provides a production-grade JSON logger with correlation IDs, child loggers, and Prometheus integration. However, it's barely adopted — 99%+ of error logging across the codebase uses raw console.error().

Metrics

Prometheus metrics available via @cc/monitoring:

import { metrics } from '@cc/monitoring';
metrics.counter('quotes_created').inc();
metrics.histogram('request_duration_ms').start();

---

Realtime Service

Node.js WebSocket server at port 4001 with Redis pub/sub backend.

Endpoints:

• GET /health — Server health + stats
• GET /metrics — Prometheus metrics
• POST /broadcast — Publish events (requires auth header)
• WS / — Main WebSocket connection

Channels: user:{userId}, customer:{customerId}, shop:{shopId} Features: Presence tracking, message recovery (replay buffer), connection heartbeats, graceful disconnect delay (10s)

---

Desktop App (Tauri 2.x)

Native desktop app built with Tauri (Rust backend), React 19, Vite 6, React Router 7, and Zustand for state.

Features:

• 13 modules: Dashboard, POS, Kiosk, Customers, Tickets, Diagnostics, Work Orders, Inventory, Quotes, Builds, Reports, Settings, Portal
• Offline queue with sync-on-reconnect
• Role-based UI (admin, manager, technician, sales, readonly)
• HashRouter for SPA routing (no server-side routing)

---

Development Commands

pnpm install              # Install dependencies
pnpm dev                  # Start web + realtime
pnpm dev --filter cc-pos  # Start specific app
pnpm build                # Build web + realtime
pnpm build:all            # Build all apps
pnpm lint                 # ESLint
pnpm lint:security        # Security-focused ESLint (web app)
pnpm typecheck            # TypeScript check
pnpm format               # Prettier
pnpm storybook            # Component docs (web app)
pnpm analyze              # Bundle analysis

---

Key Conventions

Naming

• Event types: dot-separated (quote.approved, ticket.created)
• Database tables: snake_case (warranty_plan, work_order)
• TypeScript types: PascalCase (Quote, WorkOrder)
• Functions: camelCase (calculateTotal, publishEvent)
• Components: PascalCase (QuoteList, WorkOrderForm)
• Directories: kebab-case (cc-quote, cc-intake)
• Git branches: feature/description, fix/description, claude/description

API Routes

• Base: /api/{resource} (no version prefix)
• Methods: GET (list/single), POST (create), PUT (full update), PATCH (partial), DELETE
• Pagination: ?page=1&limit=20&sort=field&order=asc
• Filtering: ?status=pending&customerId=123

TypeScript

• Root tsconfig.base.json: strict: true, noUnusedLocals, noUnusedParameters, noUncheckedIndexedAccess
• All apps extend this base config
• ESLint enforces consistent-type-imports and warns on no-explicit-any

Environment Variables

DATABASE_URL=postgresql://...
REDIS_URL=redis://localhost:6379/0
AUTH_SECRET=...
JWT_EXPIRES_IN=24h
NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_REALTIME_URL=ws://localhost:4001
LOG_LEVEL=info

---

Known Issues (from March 2026 audit)

These are documented issues found during a technical audit. Check the audit report (CC-Platform-V3-Technical-Audit.md in the v3 root) for full details:

• Security: SQL injection vector in packages/db/src/client.ts:165, missing auth on some micro-app API routes, no rate limiting on login
• Testing: 22/24 apps/packages have zero tests, CI allows broken PRs to merge
• TypeScript: 253+ non-null assertions, 40+ explicit any usages
• Logging: @cc/monitoring logger used in only 1 API route; rest uses console.error()
• Database: Duplicate migration numbers (007, 008), generated column + trigger conflicts
• UI: Hardcoded colors in login page and command palette, missing aria-labels on icon buttons
• DevOps: Deployment pipeline not implemented (echo statements), E2E tests commented out

---

When Working on CC Platform

Before Starting

1. Understand the flow — is this cross-app? Follow the event chain.
2. Check the domain — does this belong in web, a micro-app, or a new package?
3. Consider the schema — new tables need a numbered migration in packages/db/migrations/
4. Plan events — what should this publish to @cc/events?

During Development

1. Run tests: pnpm test after meaningful changes (in apps/web)
2. Check types: pnpm typecheck
3. Use the authorize() pattern on all new API routes
4. Use @cc/monitoring logger instead of console.error()
5. Use semantic design tokens from @cc/ui, not raw Tailwind colors

Common Workflows

Adding a feature to web app:

1. Add/update Zod schema in @cc/schemas or inline
2. Add migration if needed in packages/db/migrations/
3. Add server logic in apps/web/server/domains/
4. Add API route in apps/web/app/api/
5. Add UI in apps/web/app/(dashboard)/
6. Publish event if cross-app via @cc/events
7. Write tests

Adding a feature to a micro-app:

1. Same as above but in the micro-app's directory
2. Remember: auth may not be wired up yet — add authorize() calls
3. State goes in Zustand stores, not Redux

Cross-app integration:

1. Define event type in @cc/events/src/schemas.ts
2. Publisher app publishes event
3. Subscriber app creates event handler
4. Realtime service bridges events to WebSocket clients

---

Useful Links

• Local Dashboard: http://localhost:3000
• Prometheus: http://prometheus.cc.local:9090
• Grafana: http://grafana.cc.local:3000
• API Health: http://[app].cc.local/api/health/ready