10k-experts-platform

10000 Experts Development Guidelines

⚠️ CRITICAL: Before doing ANY work, read SESSION_START.md and CRITICAL_ARCHITECTURE.md in this directory.

Auto-generated from all feature plans. Last updated: 2025-10-25

Active Technologies

Backend Stack

• Runtime: Node.js 18-20 LTS with TypeScript 5.x
• Framework: Express.js 4.x (RESTful API)
• Database: PostgreSQL 15+ with row-level security, JSONB support, and strong ACID compliance
• ORM: Prisma 5.x
• Caching & Sessions: Redis 7.x (session store, rate limiting, wizard sessions, AI cache)
• Queue System: BullMQ 4.x (async processing, webhooks)
• Authentication: JWT with Redis session store

Frontend Stack

• Framework: React 18+ with TypeScript
• Forms: React Hook Form 7.x
• Testing: Jest + React Testing Library + Cypress

External Services

• AI: Anthropic Claude API (Haiku model for brief enhancement)
• Email: Microsoft Graph API (via existing M365 tenant)
• Payments: Stripe Payment Methods API, gpay.co.za SDK
• Storage: Azure Blob Storage (file attachments)
• Security: ClamAV (virus scanning)

Infrastructure

• Platform: Linux servers (Docker containers)
• Deployment: Horizontally scalable via load balancer
• Testing: Jest, Supertest, contract testing for OpenAPI compliance

Project Structure

backend/
├── src/
│   ├── models/              # Prisma schema and generated types
│   ├── services/            # Business logic layer
│   ├── api/                 # Express route handlers
│   ├── lib/                 # Shared utilities
│   └── config/              # Configuration
├── tests/
│   ├── contract/            # OpenAPI contract tests
│   ├── integration/         # Integration tests
│   └── unit/                # Unit tests
└── prisma/
    └── migrations/          # Database migrations

frontend/
├── src/
│   ├── components/          # React components
│   ├── services/            # API clients
│   ├── hooks/               # React hooks
│   └── context/             # React context
└── tests/

specs/
└── [###-feature]/           # Feature-specific documentation
    ├── spec.md
    ├── plan.md
    ├── research.md
    ├── data-model.md
    ├── quickstart.md
    ├── contracts/
    └── tasks.md

Commands

# Development
npm run dev           # Start development server

# Testing
npm test              # Run all tests
npm run test:unit     # Run unit tests only
npm run test:integration  # Run integration tests only
npm run test:contract     # Run contract tests
npm run test:coverage     # Generate coverage report

# Quality
npm run lint          # Run linter
npm run format        # Format code with Prettier

# Database
npx prisma migrate dev    # Run database migrations
npx prisma db seed        # Seed database
npx prisma generate       # Generate Prisma Client

# Pre-Commit Verification (REQUIRED before every commit)
.\scripts\pre-commit-check.ps1   # Windows
./scripts/pre-commit-check.sh    # Linux/Mac

Commit Policy

⚠️ MANDATORY: Run pre-commit verification before EVERY commit to GitHub

See COMMIT_POLICY.md for complete details.

Quick Reference

1. Make code changes
2. Test locally
3. Run: .\scripts\pre-commit-check.ps1
4. Fix any errors if checks fail
5. Re-run until ALL checks pass (12/12)
6. Only then: git add . → git commit → git push

Policy: 100% error-free GitHub repository at all times.

Code Style

• Node.js/TypeScript: Follow standard TypeScript conventions
• API Design: RESTful principles, OpenAPI 3.0 contract-first
• Database: Row-level security, idempotency for financial operations
• Testing: Contract, integration, and unit tests required
• Error Handling: Structured error responses with proper HTTP status codes