Reference Implementations

Working examples that mirror the main project structure for faster development

Overview

This directory contains working, tested examples that demonstrate how to implement the patterns and architectures described in our documentation. Each example provides a clear starting point for building production features.

📚 Documentation → Examples → Implementation Flow

Our unique three-stage learning approach:

1. 📖 Learn: Read comprehensive documentation to understand concepts
2. 🔬 Study: Examine working reference implementations
3. 🚀 Implement: Build production features with confidence

📁 Directory Structure

This structure mirrors the main project architecture for easy navigation:

reference-implementations/
├── core/                        # Domain logic & shared utilities examples
│   ├── domains/                 # Business logic implementations
│   │   ├── products/            # Product domain examples
│   │   ├── users/               # User domain examples
│   │   └── auth/                # Authentication examples
│   └── shared/                  # Shared utilities examples
│       ├── api/                 # API client patterns
│       ├── hooks/               # Generic hook implementations  
│       ├── utils/               # Utility function examples
│       └── types/               # Cross-domain type examples
│
├── features/                    # Feature implementation examples
│   ├── product-catalog/         # Product browsing feature
│   ├── shopping-cart/           # Shopping cart feature
│   └── user-authentication/     # Auth flow feature
│
├── ui/                          # UI component implementations
│   ├── foundation/              # Basic building blocks
│   ├── patterns/                # Composed UI patterns
│   └── business/                # Domain-aware components
│
└── docs/                        # Documentation examples
    ├── guides/                  # Implementation guides
    ├── patterns/                # Code pattern examples
    └── best-practices/          # Best practice implementations

🚀 Getting Started

1. Explore by Layer

Start with what you need to build:

• Building UI components? → Check ui/foundation/ for basic components
• Creating complex patterns? → Explore ui/patterns/ for composed components
• Implementing business logic? → Study core/domains/ for domain patterns
• Building complete features? → Review features/ for full implementations

2. Follow the Examples

Each directory contains:

• Working code examples with real implementations
• README.md explaining the patterns and approach
• Testing patterns showing how to test the code
• Links back to documentation for deeper understanding

3. Copy and Adapt

Examples are designed to be template-ready:

• Copy the pattern that matches your need
• Adapt it to your specific requirements
• Follow the established conventions
• Test thoroughly

🔗 Cross-References

From Documentation to Examples

Every documentation page includes links to relevant examples:

For implementation details, see the [Button Reference Implementation](/docs/reference-implementations/ui/foundation/Button).

From Examples to Documentation

Every example links back to the comprehensive documentation:

For complete architectural guidance, see the [UI Development Guide](/docs/ui-development).

🎯 Key Benefits

✅ Working Code

All examples are tested and functional - no pseudocode or broken examples.

✅ Mirror Structure

1:1 mapping with main project architecture makes navigation intuitive.

✅ Progressive Learning

From simple examples to complex patterns, building understanding step by step.

✅ Template Ready

Copy-paste starting points that follow all established conventions.

✅ Best Practices

Every example demonstrates recommended patterns and approaches.

📖 Usage Patterns

For New Features

1. Check if similar feature exists in features/
2. Review relevant domain examples in core/domains/
3. Study UI components in ui/ that you'll need
4. Copy and adapt the closest example

For New Components

1. Determine component layer (foundation/patterns/business)
2. Study similar components in the appropriate ui/ subdirectory
3. Copy the component structure and adapt
4. Follow the testing patterns shown

For Domain Logic

1. Check core/domains/ for similar business logic
2. Study the API, hooks, and types patterns
3. Review core/shared/ for utility patterns
4. Implement following the established conventions

🧪 Testing

All examples include testing patterns:

• Unit tests for individual functions and components
• Integration tests for feature workflows
• Component tests for UI behavior
• Hook tests for custom React hooks

📋 Contributing Guidelines

When adding new examples:

1. Follow the structure - Place examples in the correct directory
2. Include README - Explain the pattern and usage
3. Add tests - Show how to test the implementation
4. Link documentation - Cross-reference relevant docs
5. Keep it real - Use realistic data and scenarios

🔍 Quick Reference

Most Common Examples

• Button Component - Basic interactive component
• API Client Architecture - HTTP client configuration
• Products Domain - Business logic patterns
• user-authentication - Complete auth flow

Documentation Entry Points

• Project Structure - Overall architecture
• UI Development - Component development guide
• Domain Architecture Guide - Business logic patterns
• Feature Implementation Decision Tree - Implementation guidance

Need help? Check the documentation first, then study the relevant examples, and you'll have everything you need to implement features confidently! 🚀