ClaudeForge/skill/examples/modular-root-CLAUDE.md

CLAUDE.md

This file provides top-level guidance for Claude Code when working with this full-stack project.

Overview

Full-stack application with separated backend API and frontend SPA. Uses modular CLAUDE.md architecture with context-specific files for detailed guidance. Medium team (12 developers) in production phase.

Quick Navigation

• Backend Guidelines - API, services, database operations
• Frontend Guidelines - Components, state management, styling
• Database Operations - Schemas, migrations, query optimization
• CI/CD Workflows - Automation, testing, deployments

Project Structure

project-root/
├── backend/
│   ├── src/
│   │   ├── controllers/     # API route handlers
│   │   ├── services/        # Business logic
│   │   ├── models/          # Database models
│   │   ├── middleware/      # Express middleware
│   │   └── utils/           # Shared utilities
│   ├── tests/               # Backend tests
│   └── CLAUDE.md           # Backend-specific guidance
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── pages/           # Page components
│   │   ├── hooks/           # Custom hooks
│   │   ├── store/           # State management
│   │   └── styles/          # CSS/styling
│   ├── public/              # Static assets
│   └── CLAUDE.md           # Frontend-specific guidance
├── database/
│   ├── migrations/          # Schema migrations
│   ├── seeds/               # Seed data
│   └── CLAUDE.md           # Database guidance
├── .github/
│   ├── workflows/           # CI/CD workflows
│   └── CLAUDE.md           # CI/CD guidance
├── docker-compose.yml
├── package.json
└── README.md

File Structure

This project uses modular architecture with context-specific CLAUDE.md files:

• backend/ - Express API server
  • See backend/CLAUDE.md for API design, error handling, testing
• frontend/ - React SPA
  • See frontend/CLAUDE.md for component standards, state, styling
• database/ - PostgreSQL database
  • See database/CLAUDE.md for migrations, schemas, queries
• .github/ - CI/CD workflows
  • See .github/CLAUDE.md for deployment, automation

Architecture

Stack: React SPA + Express API + PostgreSQL + Redis Cache

Services:

• Frontend: React 18 with TypeScript, served via Nginx
• Backend: Node.js 20 with Express 4, TypeScript
• Database: PostgreSQL 15 with Prisma ORM
• Cache: Redis 7 for session and data caching
• Message Queue: RabbitMQ for async processing
• Infrastructure: Docker containers, Kubernetes orchestration

Flow:

Client (React) → Nginx → Express API → PostgreSQL
                              ↓
                          Redis Cache
                              ↓
                         RabbitMQ Queue

Setup & Installation

# Install dependencies for entire monorepo
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# Start all services with Docker
docker-compose up -d

# Run database migrations
npm run db:migrate

# Seed initial data
npm run db:seed

# Start development servers
npm run dev              # Starts backend and frontend

Core Principles

1. Test-Driven Development: Write tests before implementation
2. Type Safety First: Use TypeScript strict mode throughout
3. Component Composition: Favor small, reusable components
4. API Design: RESTful conventions with proper versioning
5. Error Handling: Comprehensive error handling from the start
6. Performance: Optimize for scale (caching, CDN, lazy loading)

Tech Stack

• Frontend: React 18, TypeScript 5, Tailwind CSS, React Query
• Backend: Node.js 20, Express 4, TypeScript, Prisma
• Database: PostgreSQL 15, Redis 7
• Infrastructure: Docker, Kubernetes, Nginx, GitHub Actions
• Testing: Jest, React Testing Library, Supertest, Playwright

Development Workflow

1. Feature Development:

   • Create feature branch: git checkout -b feature/name
   • Work in appropriate context (backend/ or frontend/)
   • Follow context-specific CLAUDE.md guidelines
   • Write tests first (TDD)
   • Run local validation: npm run lint && npm test

2. Code Review:

   • Create PR with detailed description
   • Ensure CI passes (lint, tests, build)
   • Get minimum 2 approvals
   • Address review comments

3. Deployment:

   • Merge to main triggers staging deployment
   • QA validation on staging
   • Manual promotion to production
   • Monitor metrics and logs

Quick Reference

# Development
npm run dev:backend      # Start backend server (port 3000)
npm run dev:frontend     # Start frontend dev server (port 5173)
npm run dev              # Start both servers
npm test                 # Run all tests (backend + frontend)
npm run lint             # Lint all code

# Production
npm run build            # Build frontend and backend
npm run start            # Start production servers

# Database
npm run db:migrate       # Run migrations
npm run db:seed          # Seed data
npm run db:reset         # Reset database (dev only)

# Docker
docker-compose up -d     # Start all services
docker-compose logs -f   # View logs
docker-compose down      # Stop all services

Testing Strategy

• Unit Tests: All business logic (80%+ coverage)
• Integration Tests: API endpoints and database operations
• E2E Tests: Critical user flows with Playwright
• Performance Tests: Load testing for API endpoints
• Security Tests: OWASP compliance scans

Important Notes

• Context-Specific Guidelines: Always check subdirectory CLAUDE.md files for detailed guidance
• Modular Architecture: Each major component has its own CLAUDE.md file
• Navigation: Use Quick Navigation section to find relevant guidelines
• Production Ready: This is a production-grade setup with enterprise patterns

---

For detailed guidelines, see context-specific CLAUDE.md files in subdirectories.

Project Type: Full-Stack Application (Production) Team Size: Medium (12 developers) Architecture: Modular with context-specific CLAUDE.md files Lines: ~150 (Modular root template with native format)