Skip to main content

​
Frontend Application Catalog

​
Overview

ReptiDex’s frontend ecosystem consists of 4 core applications and 2 shared packages, built with a simplified, maintainable architecture optimized for solo developer operations while maintaining scalability and code reuse.
Applications: 4 core apps
Shared Packages: 2 packages
Architecture: Next.js 15 + Material UI + Monorepo
Technology Stack: TypeScript, Zustand + React Query, Docker Compose deployment

​
Frontend Architecture

Core Applications (4)

web-public - Marketing, discovery & purchasing
web-breeder - Breeding management & sales
web-admin - Administration & moderation
web-embed - Embeddable widgets

Shared Packages (2)

@reptidex/ui - Complete design system
@reptidex/core - Business logic & APIs

​
Core Applications

​
Frontend Applications

Marketing, Discovery & Animal PurchasingPurpose: Public-facing application for marketing, animal discovery, and purchasing
Port: 3000
Users: Anonymous visitors, buyers
Status: In DevelopmentKey Features:
  • Marketing and landing pages
  • Animal search and discovery
  • Public breeder profiles
  • Animal detail pages with pedigrees
  • Purchase inquiry system
  • SEO-optimized content
Routes:
  • / - Homepage and marketing
  • /search - Animal search and browse
  • /breeders/{id} - Public breeder profiles
  • /animals/{id} - Animal detail pages
  • /about, /pricing, /contact - Marketing pages
Technology:
  • Next.js 15 with App Router
  • Material UI components via @reptidex/ui
  • Static generation for SEO
  • Server-side rendering for dynamic content
Breeding Management & Animal SalesPurpose: Comprehensive breeder workspace for managing animals, lineage, and sales
Port: 3001
Users: Breeders, organization members
Status: PlannedKey Features:
  • Animal registry and management
  • Lineage tracking and pedigree visualization
  • Breeding pair and clutch management
  • Marketplace listing creation
  • Sales and inventory management
  • Media upload and organization
Routes:
  • /dashboard - Breeder dashboard overview
  • /animals - Animal registry and management
  • /breeding - Breeding pairs and clutches
  • /lineage - Pedigree trees and lineage
  • /marketplace - Listing management
  • /media - Photo and file management
  • /settings - Account and organization settings
Technology:
  • Next.js 15 with App Router
  • Material UI components via @reptidex/ui
  • Real-time updates for breeding data
  • Advanced form handling for complex data
Administration & Platform ModerationPurpose: Administrative interface for platform management and moderation
Port: 3002
Users: ReptiDex admins, support staff
Status: PlannedKey Features:
  • User and organization management
  • Content moderation and review
  • System configuration and feature flags
  • Analytics dashboards and reporting
  • Audit logs and compliance tools
  • Integration management
Routes:
  • /dashboard - Admin dashboard
  • /users - User management
  • /organizations - Organization oversight
  • /content - Content moderation
  • /system - System configuration
  • /analytics - Platform analytics
  • /compliance - Audit and compliance
Technology:
  • Next.js 15 with App Router
  • Material UI components via @reptidex/ui
  • Advanced data tables and charts
  • Real-time monitoring dashboards
Embeddable Widgets for External SitesPurpose: Lightweight embeddable widgets for external breeder websites
Port: 3003
Users: External website visitors
Status: PlannedKey Features:
  • Animal profile cards
  • Pedigree tree widgets
  • Breeder showcase displays
  • Marketplace listing embeds
  • Responsive widget sizing
  • Customizable styling
Routes:
  • /embed/animal/{id} - Animal profile widget
  • /embed/pedigree/{id} - Pedigree tree widget
  • /embed/breeder/{id} - Breeder showcase
  • /embed/listing/{id} - Marketplace listing
  • /embed/configure - Widget configuration
Technology:
  • Vanilla JS + React for minimal bundle size
  • Custom styling system for external integration
  • CDN-optimized delivery
  • Iframe embedding support

​
Shared Package Architecture

​
@reptidex/ui Package

Complete UI and Design System
Material UI Theme & Custom ComponentsIncluded Components:
  • Material UI Theme: Custom theme with ReptiDex branding
  • Layout Components: AppBar, Navigation, Footer, Sidebar
  • Form Components: Enhanced MUI form controls with validation
  • Data Display: Tables, Cards, Lists with reptile-specific styling
  • Feedback: Snackbars, Dialogs, Progress indicators
  • Navigation: Breadcrumbs, Pagination, Tabs
  • Charts: Chart.js wrappers for analytics and data visualization
Design Tokens:
  • Color palette optimized for reptile imagery
  • Typography scale for readability
  • Spacing and layout constants
  • Component variants and themes
  • Icon library with reptile-specific icons
Features:
  • Dark/light mode support
  • Responsive design patterns
  • Accessibility compliance (WCAG 2.1)
  • TypeScript component props
  • Storybook documentation

​
@reptidex/core Package

Business Logic & API Integration
Comprehensive Business Logic and API IntegrationAPI Clients:
  • Service Clients: Type-safe clients for all 6 backend services
  • Authentication: JWT token management and refresh logic
  • Error Handling: Standardized error handling and retry logic
  • Request/Response: Type-safe request/response handling
  • Cache Management: Intelligent caching strategies
State Management:
  • Zustand Stores: Lightweight state management for UI state
  • React Query: Server state management with caching and sync
  • Auth State: Authentication and user context management
  • Form State: Complex form state management
  • Cache Invalidation: Optimistic updates and cache sync
Business Logic:
  • Animal Management: Animal CRUD operations and validation
  • Lineage Calculations: Pedigree tree generation and genetics
  • Breeding Logic: Breeding pair management and predictions
  • Commerce Operations: Marketplace and transaction handling
  • Search Logic: Search query building and result processing
Utilities:
  • Type Definitions: Complete TypeScript types for all entities
  • Validation Schemas: Zod schemas for runtime validation
  • Date/Time Utilities: Formatting and manipulation helpers
  • Currency/Number: Formatting for prices and measurements
  • File Upload: Direct-to-S3 upload helpers
  • Analytics: Event tracking and metrics collection

​
Application Dependencies

​
Package Dependency Structure

​
Technology Stack

Frontend Framework

Next.js 15 with App Router
React 18 with concurrent features
TypeScript for type safety
Material UI (MUI) for components

State & Data

Zustand for client state
React Query for server state
Zod for validation
React Hook Form for forms

Development

Docker Compose for local dev
Turbo for monorepo builds
Jest + Playwright for testing
Storybook for component docs

Deployment

Docker containers for apps
CloudFront CDN for assets
Application Load Balancer routing
EC2 instances for hosting

​
Development Workflow

​
Local Development Setup

1

Prerequisites

Docker & Docker Compose for containerized development
Node.js 18+ for package management
Git for version control
2

Repository Setup

Clone repository and install dependencies
Build shared packages (@reptidex/ui, @reptidex/core)
Start development servers via Docker Compose
3

Development Flow

Hot reloading for all applications
Shared package updates automatically rebuild
Type checking across all packages
Integrated testing with backend services

​
Package Development

Building and Testing Shared Packages@reptidex/ui Development:
  • Storybook for component development
  • Visual regression testing
  • Accessibility testing
  • Design token validation
@reptidex/core Development:
  • Unit tests for business logic
  • API client testing with MSW
  • Type safety validation
  • Integration tests with backend
Build Process:
# Build shared packages
npm run build:packages

# Start all applications
docker-compose up -d

# Development with hot reload
npm run dev:all

​
Deployment Architecture

Docker-based Deployment StrategyApplication Containers:
  • Each application builds to a separate Docker image
  • Shared packages are built and included at build time
  • Environment-specific configuration via environment variables
  • Health checks and graceful shutdown handling
Load Balancing:
  • Application Load Balancer routes traffic by subdomain/path
  • CloudFront CDN serves static assets
  • Session stickiness for consistent user experience
  • Auto-scaling based on traffic patterns
Deployment Pipeline:
  1. Build shared packages (@reptidex/ui, @reptidex/core)
  2. Build application Docker images
  3. Run test suites (unit, integration, e2e)
  4. Deploy to staging environment
  5. Run acceptance tests
  6. Deploy to production with rolling updates

​
Performance & Optimization

​
Bundle Optimization

  • Code Splitting: Automatic route-based code splitting
  • Tree Shaking: Unused code elimination
  • Dynamic Imports: Lazy loading for heavy components
  • Bundle Analysis: Regular bundle size monitoring

​
Caching Strategy

  • Static Assets: Long-term caching with CDN
  • API Responses: React Query caching with smart invalidation
  • Component State: Persistent state for user preferences
  • Service Worker: Offline capability for core features

​
Monitoring & Analytics

​
Performance Monitoring

  • Core Web Vitals: LCP, FID, CLS tracking
  • Real User Monitoring: Performance in production
  • Error Tracking: Client-side error collection
  • Bundle Size: Continuous bundle analysis

​
Business Analytics

  • User Behavior: Page views, interactions, conversions
  • Feature Adoption: Usage patterns across applications
  • Performance Impact: Business metrics correlation
  • A/B Testing: Feature flag driven experiments

​
Security & Best Practices

​
Security Implementation

  • Authentication: JWT token management with automatic refresh
  • Authorization: Role-based access control throughout apps
  • Data Validation: Client and server-side validation with Zod
  • Secure Communication: HTTPS for all API communication
  • Content Security Policy: XSS protection and resource restrictions

​
Development Standards

  • TypeScript Strict Mode: Full type safety across all code
  • ESLint + Prettier: Consistent code formatting and quality
  • Test Coverage: Minimum 80% test coverage requirement
  • Accessibility: WCAG 2.1 AA compliance
  • Performance Budget: Bundle size and performance thresholds
This simplified frontend architecture balances maintainability with functionality, providing a solid foundation for ReptiDex’s user interfaces while remaining manageable for a solo developer.