📚 Apex Phase 1 Reference Guide

Status: ✅ Complete (2026-01-30)
Pass Rate: 100% (16/16 nuclear tests, 106/106 unit tests)
Purpose: Knowledge base for Phase 2+ development

🎯 Phase 1 Achievement Summary

Core Infrastructure (Arch-Core-01, Arch-Core-02)

• •Turborepo: Build pipeline with caching (turbo.json)
• •Docker Stack: 4 services operational
  • •PostgreSQL with pgvector v0.5.1
  • •Redis v7-alpine
  • •MinIO (S3-compatible storage)
  • •Traefik v3.0 (reverse proxy)

Security Protocols (S0-S8) - 100% Compliance ✅

Super Admin Features

• •Super-#01: Tenant Overview API (9/9 tests ✅)
• •Super-#21: Blueprints Editor CRUD (8/8 tests ✅)

Infrastructure Packages

• •@apex/redis: Connection management, caching (8 tests)
• •@apex/storage: MinIO integration (5 tests)
• •@apex/monitoring: Sentry/GlitchTip (7 tests)

📁 Critical File Locations

Configuration

turbo.json                          # Build pipeline
docker-compose.yml                  # Infrastructure stack
.env.example                        # Environment template

Security Implementations

packages/config/                    # S1: Env validation
packages/db/middleware/             # S2: Tenant isolation
packages/provisioning/              # Provisioning engine
packages/encryption/                # S7: AES-256-GCM
packages/security/middlewares/      # S8: Helmet

Super Admin

apps/api/src/modules/blueprints/    # Super-#21
apps/api/src/modules/tenants/       # Super-#01

Test Suites

scripts/nuclear-test-phase-1.ts     # Comprehensive validation
scripts/verify-infrastructure.ts    # Quick health check

🔧 Common Commands

Development

bun dev                             # Start all apps
bun test                            # Run all tests
bun test --coverage                 # With coverage report

Infrastructure

docker-compose up -d                # Start all services
docker-compose ps                   # Check service status
docker exec apex-postgres psql ...  # Database access

Verification

bun scripts/verify-infrastructure.ts    # Quick health check
bun scripts/nuclear-test-phase-1.ts    # Full validation

Provisioning

bun scripts/provision-tenant.ts --store-name=test --owner-email=test@example.com

🐛 Lessons Learned (Critical Fixes Applied)

1. Audit Logging Parameter Binding

Issue: Using Drizzle's sql template caused "ghost parameters"
Solution: Use pool.query() with explicit parameters
File: packages/provisioning/src/services/schema-creator.service.ts

// ❌ WRONG - caused ghost parameters
await this.db.execute(sql`INSERT INTO audit_logs VALUES (${x}, ${y})`);

// ✅ CORRECT - explicit parameter binding
await this.pool.query(
  'INSERT INTO audit_logs (user_id, action, tenant_id, duration, status) VALUES ($1, $2, $3, $4, $5)',
  ['system', action, tenantId, duration, 'success']
);

2. Test Coverage Gap

Issue: Constructor not tested in TenantIsolationMiddleware
Solution: Added explicit test for static initialization
Learning: Test all code paths including constructors

3. Traefik Permissions

Issue: EACCES error for dynamic routes directory
Solution: chown apex-v2-dev:apex-v2-dev infra/docker/traefik/dynamic
Learning: Verify file permissions after deployment

4. pgvector Extension

Issue: Standard postgres image lacks vector support
Solution: Use ankane/pgvector:latest image
File: docker-compose.yml

🧪 Testing Standards Established

Unit Test Structure

describe('ServiceName', () => {
  let service: ServiceName;
  let mockDependency: any;

  beforeEach(() => {
    mockDependency = { method: mock(() => Promise.resolve()) };
    service = new ServiceName(mockDependency);
  });

  it('should handle success case', async () => { /* ... */ });
  it('should handle error case', async () => { /* ... */ });
  it('should validate edge case', async () => { /* ... */ });
});

Nuclear Test Categories

1. •Core Infrastructure (6 tests): Docker services, extensions
2. •Security Protocols (4 tests): S0-S8 compliance
3. •Super Admin (2 tests): Feature APIs
4. •Infrastructure Packages (3 tests): Redis, Storage, Monitoring
5. •Provisioning Engine (1 test): End-to-end flow

📊 Performance Benchmarks

🚀 Phase 2 Preparation

Dependencies Ready

• • Turborepo build system
• • Docker infrastructure
• • Security protocols enforced
• • Database with pgvector for AI features
• • Storage service (MinIO) for file uploads
• • Monitoring service for error tracking

Next Steps

1. •Tenant Storefront (Product catalog, cart, checkout)
2. •Admin Panel (Inventory, orders, settings)
3. •Payment Integration (Stripe Connect)
4. •Email Notifications (Mailpit → SendGrid)

⚠️ Critical Reminders for Phase 2

Always Follow S0 Protocol

• •Every new .ts file needs .spec.ts
• •Minimum 90% coverage per file
• •Zero exceptions - this is non-negotiable

Use Established Patterns

• •Zod schemas for all DTOs
• •pool.query() for audit logs (not db.execute)
• •Mock dependencies in tests
• •Verify on server, not just locally

Nuclear Testing

• •Add new tests to nuclear-test-phase-1.ts (or create Phase 2 version)
• •Maintain 100% pass rate
• •Run before every handover

📞 Quick Reference

Test Coverage Command:

bun test --coverage | grep "All files"

Database Access:

docker exec apex-postgres psql -U apex -d apex

Redis Check:

docker exec apex-redis redis-cli ping
# Expected: PONG

MinIO Console:

http://localhost:9001
User: admin
Pass: minio2026

Last Updated: 2026-01-30
Version: Phase 1 Final
Status: Production Ready ✅