workout-app

RailsReactTypeScriptDocker
Image 1
Image 2
Image 3

LeftyWorkout - Containerized Infrastructure & Security Architecture

Situation

Building a full-stack workout tracking application (Rails 8 API + React TypeScript frontend) required containerized infrastructure with security-first architecture across multiple environments. The challenge was to implement environment-based configuration management with secure defaults while maintaining deployment flexibility, integrate email delivery with external SMTP relay server while ensuring environment-aware communication, and create a device token security system balancing security with user experience.

Additionally, the infrastructure needed to support multiple environments (dev/test/prod) with different configurations, ensure secure defaults (2FA/activation enabled), maintain environment isolation, support zero-downtime deployments, handle container networking and service discovery, and secure email delivery without external SMTP service. As documentation grew to 100+ files, efficient navigation for humans and AI agents became increasingly important.

The system needed comprehensive authentication with multi-factor authentication (2FA), device token system, email activation workflow, and automated deployment workflows. All infrastructure needed to be version-controlled for replicability.

Task

The goal was to engineer containerized full-stack infrastructure for LeftyWorkout with Docker Compose orchestration across multiple environments. The solution needed to:

  • Implement security-first architecture including multi-factor authentication (2FA), device token system, email activation workflow, and SMTP relay integration
  • Create environment-based configuration management with secure defaults
  • Implement automated deployment workflows
  • Build comprehensive documentation system with Router/Catalog for efficient navigation
  • Support multiple environments (dev/test/prod) with environment isolation
  • Ensure zero-downtime deployments
  • Version-control all infrastructure for replicability

Success criteria included: complete Docker Compose setup with multi-container architecture, comprehensive authentication system with 2FA and device tokens, automated deployment scripts with environment auto-detection, Router/Catalog documentation system, and comprehensive test coverage for all authentication flows.

Action

Containerized Infrastructure Architecture

Implemented multi-container architecture orchestrated via Docker Compose:

  • Backend: Rails 8 API container
  • Frontend: React TypeScript SPA container
  • Database: PostgreSQL container
  • Service Discovery: Docker Compose service discovery enabling container-to-container communication
  • Environment Isolation: Separate containers and networks for dev/test/prod environments
  • Result: Complete containerization enabling consistent deployments across environments

Environment-Based Configuration Management

Created environment-specific configuration with secure defaults:

  • Environment-Specific .env Files: .env.dev, .env.test, .env.prod with git-crypt encryption
  • Docker Compose Service Discovery: Automatic service discovery via environment variable injection
  • Feature Flags: ENABLE_2FA, ENABLE_EMAIL_ACTIVATION, ENABLE_SIGNUP with secure defaults (all true)
  • Automated Deployment Scripts: Environment auto-detection and zero-downtime strategy
  • Result: Flexible configuration management with secure defaults, enabling environment-specific customization while maintaining security

SMTP Relay Integration with Environment Awareness

Configured SMTP settings per environment with environment-aware communication:

  • SMTP Relay Server: Integration with external SMTP relay (192.168.8.89)
  • Environment-Aware Email Headers: Modified email templates to include environment-aware headers (TEST/DEV/PROD) in subject lines and email bodies
  • Error Handling and Logging: Comprehensive error handling and logging for email delivery
  • Result: Prevents user confusion and ensures reliable email delivery across all environments

Device Token Security System

Created DeviceToken model with composite key ensuring security:

  • Composite Key: user_id + device_id + user_agent hash ensuring uniqueness per device
  • Automatic Revocation: User model callbacks on password change and 2FA disable automatically revoke device tokens
  • Server-Side Validation: Validation on every login via Docker Compose service discovery
  • Remember Device Functionality: Enables "remember device" functionality while maintaining security
  • Result: Balances security (prevent token theft/reuse) with user experience (reduce 2FA friction)

Comprehensive Authentication System

Implemented multi-factor authentication with email activation:

  • 2FA Support: Multi-factor authentication using TOTP
  • Email Activation Workflow: Email-based account activation before login
  • Device Token Integration: Automatic device token creation and validation
  • Automatic Token Revocation: Device tokens automatically revoked on security events (password change, 2FA disable)
  • Result: Comprehensive authentication system preventing unauthorized access while reducing authentication friction

Router/Catalog Documentation System

Created Router/Catalog system for efficient documentation navigation:

  • Auto-Generated Indexes: Python script (342 lines) extracts YAML frontmatter metadata and generates compact Router table
  • Router-First Retrieval Protocol: Enables efficient context scoping for AI agents and humans
  • Prevents Documentation Overload: Enables finding relevant information without loading all documentation
  • Result: Efficient knowledge management and AI agent context scoping, preventing documentation overload while maintaining comprehensive infrastructure knowledge

Test Environment Deployment

Configured test environment with proper email configuration:

  • Test Environment SMTP Settings: Configured SMTP settings for test environment
  • Environment-Aware Email Headers: Added environment-aware email headers
  • Complete Authentication Flow Testing: Tested signup → activation → login → 2FA → device token flow
  • Docker Compose Service Discovery: Verified service discovery and container networking
  • Result: Production-ready deployment with proper environment isolation

Technical Implementation Details

Architecture Decisions:

  • Multi-container architecture (Rails 8 API, React TypeScript SPA, PostgreSQL) orchestrated via Docker Compose
  • Environment-based configuration management (.env files with git-crypt encryption)
  • SMTP relay server integration (192.168.8.89) for email delivery
  • Cloudflare Tunnel for secure access
  • Feature flags with secure defaults

Implementation Strategy:

  • Docker Compose configuration with environment variable injection and service discovery
  • Feature flags (ENABLE_2FA, ENABLE_EMAIL_ACTIVATION, ENABLE_SIGNUP) with secure defaults (all true)
  • Deployment scripts with environment auto-detection and zero-downtime strategy
  • Comprehensive authentication system with 2FA, device tokens, email activation, automatic token revocation
  • Router/Catalog documentation system with auto-generated indexes (Python script, 342 lines)
  • Comprehensive test coverage (500+ lines) for all authentication flows

Observability/Operations:

  • Docker container logs (stdout/stderr) for all services
  • Rails logger for authentication events (login attempts, failures, warnings)
  • Device token last_used_at timestamp for audit trail
  • Email delivery logs (ActionMailer)
  • Test coverage (500+ lines of authentication tests)
  • Deployment logs (environment detection, configuration loading)

Infrastructure Contributions: 125+ commits, 50+ files changed (4,583 insertions, 44 deletions), comprehensive authentication system implementation

Result

Containerization Achievement

Complete Docker Compose setup with multi-container architecture (backend, frontend, database), service discovery, and environment isolation across 3 environments (dev, test, prod). The containerized approach enables consistent deployments and eliminates "works on my machine" issues.

Security Architecture Success

Comprehensive authentication system with 2FA, device tokens, email activation, and automatic token revocation on security events, preventing unauthorized access and reducing authentication friction. The device token system balances security with user experience, enabling "remember device" functionality while maintaining security.

Deployment Automation Impact

Automated deployment scripts with environment auto-detection and zero-downtime strategy, enabling consistent deployments across environments with 125+ infrastructure commits. The environment-based configuration management ensures secure defaults while maintaining deployment flexibility.

Documentation Infrastructure Excellence

Router/Catalog system (342-line Python generator) enables efficient knowledge management and AI agent context scoping, preventing documentation overload while maintaining comprehensive infrastructure knowledge. The auto-generated indexes stay synchronized with documentation, preventing documentation drift.

Test Coverage Success

500+ lines of authentication tests (backend and frontend) covering all flows, edge cases, and security scenarios, ensuring reliability and security of authentication system. The comprehensive test coverage provides confidence in deployment and reduces risk of security vulnerabilities.

Technical Stack

Docker, Docker Compose, Rails 8, React TypeScript, PostgreSQL, Devise, SMTP relay server, git-crypt, Cloudflare Tunnel, Python (documentation generator), Pundit authorization

Conclusion

The LeftyWorkout project demonstrates replicable & resilient systems engineering through containerized infrastructure with security-first architecture. By implementing comprehensive authentication with 2FA, device tokens, and email activation, the project ensures security while maintaining user experience. The holistic "full-stack" infrastructure view is evident in the integration of containerization, environment management, SMTP integration, and documentation systems. The security-first approach with secure defaults and automatic token revocation ensures robust security, while the Router/Catalog documentation system showcases systematic knowledge management. This infrastructure investment—doing it right the first time—eliminates technical debt and enables rapid development, transforming application infrastructure from manual, error-prone deployments into automated, secure, and replicable systems. The project exemplifies how systematic infrastructure engineering can deliver reliable, secure containerized applications while maintaining operational efficiency and comprehensive test coverage. The 125+ infrastructure commits demonstrate commitment to infrastructure reliability and security, showcasing enterprise-grade infrastructure engineering capabilities.