​

System Design & Architecture

​

System Purpose & Context

Primary Goal: Streamline reptile lineage tracking by creating a standardized, trusted, and transparent process across reptile species.

​

Problem Statement

ReptiDex solves critical challenges in reptile breeding:

• Eliminates guesswork and inconsistent record-keeping in reptile breeding
• Establishes shared standards for lineage tracking, making data interoperable across breeders
• Builds trust between breeders and buyers through verified, transparent records
• Positions lineage tracking as the foundation with additional features as value-add bonuses

​

Guiding Principle

Every feature in ReptiDex supports or enhances the core lineage tracking experience.

---

​

C4 Level 1: System Context

​

Primary Actors

​

External Systems

​

System Context Diagram

---

​

C4 Level 2: Container Architecture

​

Frontend Applications

Core User-Facing Applications (4)

Application	Purpose	Technology	Users
web-public	Marketing, discovery, and animal purchasing	Vite + React 19, Tailwind CSS	Anonymous visitors, buyers
web-breeder	Breeding management and animal sales	Vite + React 19, Tailwind CSS	Breeders, organization members
web-admin	Administration and platform moderation	Vite + React 19, Tailwind CSS	ReptiDex admins, support staff
web-embed	Embeddable widgets for external sites	Vanilla JS, React	External website visitors

Shared Frontend Packages (2)

Package	Purpose	Contains
@reptidex/ui	Complete UI and design system	Material UI theme, components, design tokens, icons
@reptidex/core	Business logic and API integration	API clients, types, auth, state management, utilities

​

Backend Microservices (6 Consolidated Services)

repti-core

Foundation service that supports all other domainsPurpose: Auth, Config, Billing, Events, Telemetry
Port: 8001
Database: repti_core_db
Responsibilities:

• Identity & access management (users, organizations, sessions)
• Configuration & feature flags
• Event bus & async processing
• Telemetry collection and aggregation
• Billing and subscription management

repti-animal

Core business logic for reptile-specific functionalityPurpose: Animals, Lineage, Genetics, Taxonomy, Breeding
Port: 8002
Database: repti_animal_db
Responsibilities:

• Animal records & metadata management
• Pedigree tracking & visualization
• Species taxonomy & traits
• Breeding pairs & clutches
• Genetic analysis and predictions

repti-commerce

Commerce and marketplace functionalityPurpose: Marketplace, Sales, Transactions, Inventory
Port: 8003
Database: repti_commerce_db
Responsibilities:

• Marketplace listings and discovery
• Sales transactions and order management
• Inventory tracking and availability
• Payment processing coordination
• Commerce analytics and reporting

repti-media

Media and content managementPurpose: Files, Rendering, Embeds, Content
Port: 8004
Database: repti_media_db
Responsibilities:

• File storage & CDN management
• Document/chart rendering & exports
• Embeddable widgets for external sites
• Media processing and optimization
• Content management and delivery

repti-community

Engagement and community featuresPurpose: Search, Notifications, Community, Ads
Port: 8005
Database: repti_community_db
Responsibilities:

• Search & indexing across all content
• Multi-channel notifications (email, SMS, push)
• Community features and social interactions
• Advertising and promotion management
• User engagement analytics

repti-ops

Operations and administrative functionalityPurpose: Admin, Audit, Integrations, Logging
Port: 8006
Database: repti_ops_db
Responsibilities:

• Administrative tools and dashboards
• Audit logs & compliance reporting
• Third-party integrations management
• System monitoring and alerting
• Operational analytics and insights

​

Container Diagram

---

​

Technology Stack

​

Infrastructure & Hosting

​

Development Stack

---

​

Service Communication

​

Synchronous Communication

REST APIs: Direct service-to-service calls for:

• Real-time data queries
• User-facing operations
• Administrative tasks
• Cross-service data retrieval

API Gateway: Centralized routing with:

• Authentication and authorization
• Rate limiting and throttling
• Request/response transformation
• Monitoring and analytics

​

Asynchronous Communication

Event-Driven Architecture: AWS SNS/SQS for:

• Domain events (animal.*, lineage.*, profile.*)
• Business events (breeding.*, sales.*, payments.*)
• System events (auth.*, config.*, telemetry.*)

Event Patterns:

• Fan-out: One publisher, multiple subscribers
• Request/Reply: Asynchronous request-response patterns
• Saga: Distributed transaction coordination

---

​

Data Architecture

​

Database Strategy

Database-Per-Service Architecture:

• repti_core_db: Authentication, configuration, billing, events
• repti_animal_db: Animals, lineage, genetics, taxonomy, breeding
• repti_commerce_db: Marketplace, sales, transactions, inventory
• repti_media_db: File metadata, rendering jobs, embed configurations
• repti_community_db: Search indexes, notifications, community data
• repti_ops_db: Admin tools, audit logs, integrations, system logs

Data Consistency Patterns:

• Strong consistency within each service database
• Eventual consistency across services via events
• Event sourcing for critical business events
• Cross-service coordination via repti-core event orchestration

​

Caching Strategy

Multi-Level Caching

Application Cache (Redis):

• Session data and user preferences
• Frequently accessed configurations
• Computed pedigree graphs
• Search results and filters

CDN Cache (CloudFront):

• Static assets and media files
• Public profile pages
• API responses with cache headers
• Embeddable widget assets

Database Cache:

• Connection pooling
• Query result caching
• Read replicas for scaling
• Materialized views for complex queries

---

​

Security Architecture

​

Authentication & Authorization

Multi-Layered Security:

• JWT tokens (RS256) with KMS-backed keys
• Refresh token rotation
• API keys for service integration
• Role-based access control (RBAC)

Network Security:

• VPC with private subnets
• Security groups and NACLs
• WAF for application protection
• TLS 1.3 for all communications

​

Data Protection

Encryption:

• At rest: AES-256 for databases and storage
• In transit: TLS 1.3 for all network communication
• Key management: AWS KMS with rotation
• Secrets management: AWS Secrets Manager

Privacy Controls:

• Granular visibility settings
• Data anonymization for analytics
• GDPR compliance features
• Audit logging for all data access

---

​

Deployment Architecture

​

Environment Strategy

​

CI/CD Pipeline

Build Process:

1. Code commit triggers GitHub Actions
2. Automated testing (unit, integration, e2e) per service
3. Security scanning and dependency checks
4. Docker image build and push to ECR (6 service images)
5. Infrastructure updates via Terraform
6. Rolling deployment to EC2 instances with Docker Compose

Deployment Strategy:

• Docker Compose rolling updates for zero downtime
• Service-by-service deployments for gradual rollouts
• Feature flags via repti-core for controlled feature enablement
• Database migrations coordinated per service
• Rollback capabilities via previous Docker images

---

​

Related Documentation