Frontend Architecture
ReptiDex’s frontend architecture is designed for scalability, maintainability, and optimal user experience across multiple applications while maximizing code reuse through strategic shared packages.Frontend Strategy
Architecture Principles
- Application-Per-User-Journey: Separate applications for distinct user workflows and optimization needs
- Minimal Package Complexity: Keep shared packages to essential UI and core business logic only
- Service-Aligned: Frontend applications align with backend service boundaries where logical
- Performance-First: Optimize bundle sizes and loading patterns per application type
- Design System Consistency: Unified UI/UX across all applications through shared components
User-Centric Design
Breeder Journey: Comprehensive workspace for managing breeding operations and sales Buyer Journey: Streamlined discovery and purchasing experience Admin Journey: Powerful administrative tools for platform management Public Journey: SEO-optimized marketing and discovery experienceFrontend Applications
Core Applications (4)
web-public
Marketing, Discovery & PurchasingUsers: Anonymous visitors, potential buyers
Technology: Vite + React 19 + Tailwind CSS
Deployment: CDN-optimized for global performanceKey Features:
- Landing pages and marketing content
- Public animal browsing and search
- Pedigree viewing and breeder discovery
- Animal purchasing and inquiry flows
- SEO-optimized pages for search visibility
web-breeder
Breeder Workspace & Sales ManagementUsers: Authenticated breeders, organization members
Technology: Vite + React 19 + Tailwind CSS
Deployment: Authentication-required workspaceKey Features:
- Animal records and lineage management
- Breeding pairs and clutch tracking
- Inventory management and sales listings
- Analytics and breeding insights
- Organization and team collaboration
web-admin
Administrative InterfaceUsers: ReptiDex administrators, support staff
Technology: Vite + React 19 + Tailwind CSS
Deployment: Internal admin-only accessKey Features:
- User and organization management
- Content moderation and abuse handling
- System monitoring and analytics
- Feature flag and configuration management
- Support tools and customer assistance
web-embed
Embeddable WidgetsUsers: Website visitors on breeder sites
Technology: Vite + React (minimal bundle)
Deployment: CDN for external integrationKey Features:
- Pedigree tree widgets
- Breeder profile cards
- Animal listing grids
- Contact forms and inquiry widgets
- Minimal footprint for external sites
Shared Package Strategy
Simplified Package Architecture
ReptiDex uses a minimal shared package approach to balance code reuse with maintenance simplicity.@reptidex/ui - Complete UI Package
@reptidex/ui - Complete UI Package
Single comprehensive UI and design system packageComponents:
- Radix UI primitives with Tailwind CSS styling
- Complete component library (Button, Form, Modal, Table, etc.)
- Design tokens and brand guidelines
- Icon library and asset management
- Typography and spacing systems
- Single source of truth for all UI components
- Consistent design across all applications
- Easy theme updates and brand changes
- Simplified dependency management
@reptidex/core - Business Logic & Utilities
@reptidex/core - Business Logic & Utilities
Comprehensive business logic and integration packageAPI Clients:
- Generated TypeScript clients for all 6 backend services
- Request/response types and validation
- Error handling and retry logic
- TypeScript interfaces for all business entities
- Reptile-specific utilities (genetics, morphs, taxonomy)
- Authentication and permission management
- State management patterns (Zustand + React Query)
- Date formatting and validation helpers
- Constants, enums, and configuration
- Common React hooks and patterns
@reptidex/embed (Optional) - Lightweight Widgets
@reptidex/embed (Optional) - Lightweight Widgets
Minimal package for external widget integrationPurpose: Ultra-lightweight components for external websites
Bundle Size: < 50KB gzipped
Dependencies: Minimal (no heavy UI libraries, optimized React)Components:
- Standalone pedigree viewer
- Simple animal profile cards
- Contact forms and inquiry widgets
- Minimal styling and theming
Frontend-to-Backend Integration
Service Communication Patterns
Application-Specific Service Usage
| Application | Primary Services | Secondary Services |
|---|---|---|
| web-public | repti-engagement, repti-business | repti-media, repti-core |
| web-breeder | repti-business, repti-core | repti-commerce, repti-media |
| web-admin | repti-operations, repti-core | All services (admin access) |
| web-embed | repti-business, repti-media | repti-core (minimal auth) |
Technology Stack
Core Technologies
Frontend Framework
Vite for fast builds and HMR
React 19 with concurrent features
TypeScript for type safety
Radix UI + Tailwind CSS for components
React 19 with concurrent features
TypeScript for type safety
Radix UI + Tailwind CSS for components
State Management
Zustand for global state
React Query for server state
React Hook Form for form management
Zod for validation schemas
React Query for server state
React Hook Form for form management
Zod for validation schemas
Development Tools
Build & Development
Vite for fast development builds
ESLint + Prettier for code quality
Storybook for component development
Vitest + Testing Library for testing
ESLint + Prettier for code quality
Storybook for component development
Vitest + Testing Library for testing
Deployment
Static hosting for frontend apps
CloudFront CDN for global distribution
GitHub Actions for CI/CD
Docker for containerized environments
CloudFront CDN for global distribution
GitHub Actions for CI/CD
Docker for containerized environments
Application Architecture Patterns
Authentication & Authorization
State Management Pattern
Error Handling Strategy
Performance Optimization
Bundle Optimization
Code Splitting: Each application loads only required code- web-public: Heavy focus on image optimization for marketing
- web-breeder: Optimized for data-heavy interfaces
- web-embed: Minimal assets for fast external loading

