This project serves as a comprehensive guide and reference implementation for building enterprise-grade applications using Claude Code. It demonstrates best practices across the entire software development lifecycle, from initial concept through deployment and maintenance.
This guide showcases how to leverage Claude Code's capabilities to build a production-ready, full-stack application with modern technologies and enterprise-level quality standards.
This is a sample and guide project that demonstrates:
- How to structure and execute a professional development workflow
- Best practices for enterprise application development
- Integration of modern frontend and backend technologies
- Cloud-native architecture patterns with Azure
- Quality assurance and testing strategies
- Comprehensive documentation practices
- Framework: React 18+ with TypeScript
- Build Tool: Vite
- Component Library: Material-UI (MUI) 7
- State Management: TanStack Query (React Query)
- Routing: React Router (route-driven components)
- Form Management: Formik with Yup validation
- HTTP Client: Axios
- Framework: .NET 10
- Architecture: Domain-driven design with Controller/Command pattern
- API Style: RESTful APIs
- Primary Database: Azure CosmosDB (SQL API) - General storage and transactions
- Reporting Database: Microsoft SQL Server - Analytics and quick queries
- Storage: Azure Blob Storage
- Queuing: Azure Storage Queues
- Azure Functions
- Azure Blob Storage
- Azure Storage Queues
- Azure CosmosDB
- Azure SQL Database
- Deployment: Azure Bicep scripts
- Unit tests for business logic
- Regression tests using Virtuoso API
- Accessibility testing
Objective: Transform concepts into actionable development items
- Brainstorming: Document initial concepts and problem statements
- Domain Modeling: Establish core domain entities and relationships
- Data Dictionary: Create and maintain consistent terminology
- Define business terms
- Map technical implementations
- Maintain glossary for cross-team communication
- Initial concept document
- Domain model diagrams
- Data dictionary (ongoing maintenance)
Objective: Create detailed specifications and architectural decisions
-
User Stories: Write clear, testable user stories
- Format: "As a [user type], I want to [action] so that [benefit]"
- Include acceptance criteria
- Estimate complexity
-
Story Mapping: Organize stories into logical flows
- Map user journeys
- Identify MVPs and releases
- Prioritize features
-
Release Planning: Define release boundaries
- Group stories into releases
- Identify dependencies
- Set milestones
-
Interactive Wireframes: React-based working prototypes
- Functional components with state management
- User interaction flows
- State control demonstrations
- Responsive layouts
-
Accessibility Considerations: Plan for WCAG 2.1 AA compliance
- Keyboard navigation
- Screen reader compatibility
- Color contrast ratios
- ARIA labels and roles
-
Decision Analysis Tables: Document key choices
- Compare options (libraries, patterns, services)
- List pros and cons
- Score criteria (performance, maintainability, cost, team expertise)
- Record final decisions and rationale
-
Architecture Diagrams:
- System context diagrams
- Component diagrams
- Data flow diagrams
- Deployment diagrams
- Domain/Feature-Based Structure: Organize code by business domain
- Pattern-Based Coding: Favor consistent patterns over clever solutions
- Maintainability Over Complexity: Choose clarity over cleverness
- Consistent Terminology: Use data dictionary terms throughout
- User stories with acceptance criteria
- Story maps with release definitions
- Working wireframes
- Decision analysis tables
- Architecture documentation
Objective: Build the application following established patterns and best practices
frontend/
├── src/
│ ├── features/ # Feature-based modules
│ │ ├── [domain-name]/
│ │ │ ├── components/ # Feature-specific components
│ │ │ ├── hooks/ # Feature-specific hooks
│ │ │ ├── api/ # Feature API calls
│ │ │ ├── types/ # Feature TypeScript types
│ │ │ └── routes/ # Feature routes
│ ├── shared/ # Shared utilities
│ │ ├── components/ # Reusable components
│ │ ├── hooks/ # Shared hooks
│ │ ├── utils/ # Helper functions
│ │ └── types/ # Shared types
│ ├── layouts/ # Page layouts
│ ├── routes/ # Route configuration
│ └── theme/ # MUI theme configuration
backend/
├── src/
│ ├── Domain/ # Top-level domain organization
│ │ ├── [DomainName]/
│ │ │ ├── Controllers/ # API endpoints
│ │ │ ├── Commands/ # Command handlers (CQRS)
│ │ │ ├── Queries/ # Query handlers (CQRS)
│ │ │ ├── Models/ # Domain models
│ │ │ ├── Services/ # Business logic
│ │ │ ├── Validators/ # Input validation
│ │ │ └── Interfaces/ # Contracts
│ ├── Infrastructure/ # Cross-cutting concerns
│ │ ├── Data/
│ │ │ ├── CosmosDB/
│ │ │ └── SqlServer/
│ │ ├── Azure/
│ │ │ ├── Functions/
│ │ │ ├── Storage/
│ │ │ └── Queues/
│ └── Shared/ # Shared utilities
- Use functional components exclusively
- Implement custom hooks for reusable logic
- Use TanStack Query for server state
- Use React Context or state libraries for client state
- Route-driven architecture: Components mounted via routing
- Use MUI 7 components with custom theming
- Formik + Yup: All forms with validation schemas
- Axios interceptors: Centralized error handling and auth
- Controller/Command Pattern: Thin controllers, business logic in commands
- CQRS: Separate read and write operations
- Dependency Injection: Use built-in .NET DI container
- Repository Pattern: Abstract data access
- Unit of Work: Transaction management
- DTOs: Separate API models from domain models
- Meaningful names: Use data dictionary terms
- Single Responsibility: Functions/classes do one thing
- DRY Principle: Extract common logic
- SOLID Principles: Follow object-oriented best practices
- Pattern-based: Consistent patterns across codebase
- Document-based storage for transactional data
- Partition key strategy for scalability
- Consistency levels per use case
- Change feed for event streaming
- Normalized schema for analytics
- Indexed views for common queries
- Stored procedures for complex reports
- Regular sync from CosmosDB
- Functional application code
- Consistent code patterns
- Database schemas and migrations
- Azure function implementations
Objective: Ensure quality, reliability, and accessibility
-
Coverage: All non-trivial business logic
-
Frontend Testing:
- React Testing Library
- Test custom hooks
- Test utility functions
- Mock API calls
-
Backend Testing:
- xUnit or NUnit
- Test commands and queries
- Test business logic
- Mock external dependencies
- Automated Tests: Virtuoso API integration
- Test Scenarios: Cover critical user paths
- CI/CD Integration: Run on every deployment
- Automated Tools: axe-core, Lighthouse
- Manual Testing: Keyboard navigation, screen readers
- WCAG 2.1 AA Compliance: Verify all criteria
- Write tests alongside implementation
- Aim for meaningful coverage, not 100%
- Test behavior, not implementation
- Maintain test data fixtures
- Unit test suite with good coverage
- Automated regression tests
- Accessibility audit reports
- Test documentation
- Purpose: What the component does
- Props: TypeScript interfaces with descriptions
- Usage Examples: Common use cases
- Accessibility: ARIA attributes and keyboard support
- Endpoints: URL, HTTP method, purpose
- Request/Response: Schemas and examples
- Error Codes: Possible errors and meanings
- Authentication: Required permissions
- Purpose: Business operation description
- Inputs: Parameter descriptions
- Outputs: Return value description
- Side Effects: Database changes, external calls
- Tables/Collections: Schema and purpose
- Relationships: Foreign keys and references
- Indexes: Performance optimization notes
- Triggers/Procedures: Business logic documentation
- Service Purpose: Why it's used
- Configuration: Key settings
- Scaling: Performance considerations
- Cost: Resource consumption estimates
- Feature Guides: How to use each feature
- Screenshots: Visual walkthroughs
- FAQs: Common questions
- Troubleshooting: Problem resolution
- Architecture Decisions: ADRs (Architecture Decision Records)
- Integration Points: External dependencies
- Deployment Guide: Step-by-step deployment
- Monitoring: Logging and alerting
All Azure resources are provisioned using Bicep scripts:
infrastructure/
├── main.bicep # Main orchestration
├── modules/
│ ├── cosmosdb.bicep # CosmosDB resources
│ ├── sqlserver.bicep # SQL Server resources
│ ├── storage.bicep # Blob and Queue storage
│ ├── functions.bicep # Azure Functions
│ ├── webapp.bicep # Web App hosting
│ └── networking.bicep # VNets, NSGs, etc.
├── parameters/
│ ├── dev.parameters.json
│ ├── staging.parameters.json
│ └── prod.parameters.json
└── scripts/
└── deploy.sh # Deployment automation
- Validate: Test Bicep syntax and parameters
- Preview: Run what-if analysis
- Deploy: Apply infrastructure changes
- Verify: Check resource health
- Configure: Set application settings
- Deploy Code: Push application code
- Test: Run smoke tests
- Development: Minimal resources, frequent deployments
- Staging: Production-like, integration testing
- Production: Full resources, change control
This guide demonstrates how to use Claude Code throughout the development process:
- Generate user stories from requirements
- Create story maps and release plans
- Build data dictionaries
- Design architecture decision tables
- Create React wireframe components
- Generate TypeScript interfaces
- Design database schemas
- Create Bicep templates
- Scaffold project structure
- Generate boilerplate code
- Implement features following patterns
- Write unit tests
- Generate API documentation
- Create component documentation
- Write deployment guides
- Maintain data dictionary
- Write unit tests
- Create test fixtures
- Generate accessibility tests
- Build regression test suites
- Project setup and tooling
- Core infrastructure (Bicep)
- Authentication and authorization
- Base UI components and routing
- Implement primary domain features
- Database integration (CosmosDB + SQL)
- Azure Functions implementation
- Storage and queue integration
- Comprehensive testing
- Accessibility compliance
- Performance optimization
- Complete documentation
- Security audit
- Load testing
- Monitoring and alerting
- Production deployment
- Maintainability: Code is easy to understand and modify
- Testability: High test coverage of business logic
- Accessibility: WCAG 2.1 AA compliant
- Documentation: All components well-documented
- Performance: Fast load times and responsive UI
- Scalability: Architecture supports growth
- Reliability: Robust error handling and recovery
- Domain-driven design with clear boundaries
- Consistent terminology from data dictionary
- Pattern-based, maintainable code
- Comprehensive testing strategy
- Infrastructure as Code
- Detailed documentation at all levels
- Accessibility-first approach
- Modern frontend architecture
- Cloud-native backend patterns
- React Documentation
- Vite Documentation
- MUI Documentation
- TanStack Query Documentation
- Formik Documentation
This is a sample/guide project. Feel free to use it as a reference for your own projects.
This project serves as a guide. Contributions that improve the documentation or demonstrate additional best practices are welcome.
Built with Claude Code - Demonstrating enterprise-grade development practices from concept to deployment.