repti-core Service
Foundation service that supports all other domainsService Type: Foundation/Core Service
Port: 8001
Database: repti_core_db
Status: Active Development
Team Owner: Platform Team
Port: 8001
Database: repti_core_db
Status: Active Development
Team Owner: Platform Team
Purpose & Responsibilities
repti-core serves as the foundational service for the entire ReptiDex platform, providing essential infrastructure capabilities that all other services depend on.Core Responsibilities
Authentication & Authorization
- Identity & access management (users, organizations, sessions)
- JWT token generation and validation
- Role-based access control (RBAC)
- API key management for service integration
- Multi-factor authentication support
Configuration Management
- Application configuration management
- Feature flags and A/B testing
- Environment-specific settings
- Service configuration distribution
- Real-time configuration updates
Event Orchestration
- Event bus coordination and routing
- Async processing job scheduling
- Event publishing and subscription management
- Cross-service event correlation
- Event sourcing for audit trails
Billing & Subscriptions
- Subscription lifecycle management
- Payment processing coordination (Stripe/PayPal)
- Invoice generation and tracking
- Usage-based billing calculations
- Dunning and retry logic
Telemetry & Monitoring
- Application telemetry collection
- Performance metrics aggregation
- User behavior analytics
- System health monitoring
- Custom business metrics tracking
API Endpoints
Authentication Endpoints
Vivarium (Organization) Management
Configuration Endpoints
Billing Endpoints
Event Management
Database Schema
Core Tables
Users & Authentication
Users & Authentication
Vivariums & Role-Based Access Control
Vivariums & Role-Based Access Control
Vivarium Role Definitions
reptidex uses husbandry-themed role names that map to traditional RBAC permissions:- Keeper (Viewer): Read-only access to animals, pedigrees, and clutches
- Handler (Editor): Can add/update animals, pairings, clutches, and media
- Curator (Admin): Manages vivarium data and members, cannot change billing
- Herpetologist (Owner): Full rights including deleting vivarium and managing subscriptions
Database Schema
Configuration & Feature Flags
Configuration & Feature Flags
Event Publishing & Subscriptions
Published Events
Authentication Events:auth.user.created- New user registrationauth.user.updated- User profile changesauth.session.started- User loginauth.session.ended- User logoutauth.password.changed- Password updates
org.created- New organization createdorg.updated- Organization details changedorg.member.added- New member joinedorg.member.removed- Member left organizationorg.member.role.changed- Member role updated
config.updated- Configuration changesconfig.feature.toggled- Feature flag changes
billing.subscription.created- New subscriptionbilling.subscription.updated- Subscription changesbilling.invoice.created- Invoice generationbilling.payment.succeeded- Successful paymentbilling.payment.failed- Failed payment
Event Subscriptions
repti-core subscribes to events from all services for:- Telemetry Collection: Aggregating metrics from all services
- Audit Logging: Recording all system events for compliance
- System Health: Monitoring service health and performance
- Usage Tracking: Calculating usage for billing purposes
External Dependencies
Payment Processing
- Stripe: Primary payment processor
- PayPal: Alternative payment method
- Webhooks: Payment status updates and subscription events
Infrastructure
- AWS KMS: Encryption key management
- AWS SNS/SQS: Event infrastructure
- Redis: Session storage and caching
Optional Integrations
- OAuth Providers: Google, GitHub SSO
- Email Providers: Transactional email via integrations
Security Implementation
Authentication Security
- JWT Tokens: RS256 signatures with KMS-backed keys
- Refresh Token Rotation: Enhanced security for long-lived sessions
- Rate Limiting: Protection against brute force attacks
- Password Security: bcrypt hashing with configurable rounds
Authorization Framework
- Row-Level Security: Organization-scoped data access
- Role-Based Access Control: Flexible permission system
- API Key Management: Service-to-service authentication
- Audit Logging: Complete access logs for compliance
Performance & Scaling
Caching Strategy
- Session Cache: Redis for active user sessions
- Configuration Cache: In-memory caching with TTL
- Feature Flag Cache: Fast feature flag evaluation
- JWT Validation Cache: Cached public key validation
Database Optimization
- Connection Pooling: Efficient database connections
- Query Optimization: Indexed queries for performance
- Read Replicas: Scaling read operations
- Partitioning: Large table optimization strategies
Monitoring & Observability
Key Metrics
- Authentication Rate: Login success/failure rates
- API Response Times: Service performance tracking
- Event Processing: Event publication and consumption rates
- Database Performance: Query performance and connection health
Health Checks
Alerting
- Authentication Failures: High failure rate alerts
- Database Performance: Slow query detection
- Event Processing: Queue backup alerts
- External Service: Dependency failure notifications
Development Guidelines
Code Standards
- FastAPI Framework: Python 3.11+ with type hints
- Pydantic Models: Request/response validation
- Alembic Migrations: Database schema management
- pytest Testing: Comprehensive test coverage
Deployment
- Docker Container: Containerized deployment
- Environment Variables: Configuration via env vars
- Health Checks: Container health monitoring
- Rolling Updates: Zero-downtime deployments
repti-core is the foundational service that enables all other ReptiDex services. Its reliability and performance are critical to the entire platform’s operation.

