This file provides unified guidance for AI agents working with the Transformer codebase.
Transformer - A Ruby on Rails 8.0.2 string manipulation web application with modular transformation engine, YAML-based configuration, and secure Liquid templating.
bin/dev # Start development server
bin/setup # Initial project setup
bundle exec rspec # Backend tests (comprehensive: 75+ examples)
npm test # Frontend tests (Jest)
bin/rubocop # Linting (Rails Omakase style)
bin/brakeman # Security scan
bundle exec rake commit:review # Analyze changes vs project goals
bundle exec rake commit:message # Generate conventional commit
bundle exec rake transformer:list # Show available transformations
bundle exec rake transformer:validate # Validate YAML files
- Domain-Driven Design:
TransformationDefinition
as core business entity
- Adapter Pattern: Unified interface for file and database sources
- Dependency Inversion: Business logic independent of storage mechanism
- Single Responsibility: Each layer has clear, focused responsibilities
- Security-First: Function whitelisting prevents code injection
- Zeitwerk Compliance: File structure = class namespaces exactly
app/models/domain/ # Pure domain objects (no Rails dependencies)
app/adapters/ # Infrastructure adapters (File, Database)
app/services/ # Domain services & business logic
app/controllers/ # Presentation layer (HTTP concerns only)
app/models/ # ActiveRecord persistence models
config/transformations/ # File-based transformation definitions
Controllers → Registry Service → Domain Objects
↓
[File Adapter] ← → [Database Adapter]
↓
Transformation Definition (unified interface)
↓
Processing Engine → Output
Presentation → Controllers (HTTP, JSON)
Application → Services (Business Logic)
Domain → Models (Pure Business Objects)
Infrastructure → Adapters (File, Database, External APIs)
- Plan: Update
goals.md
story status before implementing
- Architecture: For complex changes, use Clean Architecture patterns (Domain → Services → Adapters → Controllers)
- Test-First: Write RSpec/Jest tests before code (mock adapters in controller tests)
- Implement: Follow Zeitwerk naming strictly, respect layer boundaries
- Quality: Run
rake commit:review
before committing
- Document: Update relevant docs and history logs
- TodoWrite Planning: Break complex refactoring into manageable steps (mirror goals.md story tasks)
- Domain First: Start with pure domain objects (no Rails dependencies)
- Adapter Pattern: Create adapters for external dependencies
- Service Layer: Coordinate between adapters and domain logic
- Controller Updates: Minimal changes, delegate to services
- Comprehensive Testing: Test each layer independently with mocking
- Story Completion: Update goals.md only when all TodoWrite tasks complete
- Story Start: Convert goals.md checklist items into TodoWrite tasks
- Dynamic Planning: Add implementation-specific subtasks as discovered
- Progress Tracking: TodoWrite provides real-time progress, goals.md provides project context
- Completion Sync: Mark goals.md story complete only when TodoWrite shows all tasks done
snake_case.rb
→ CamelCase
classapp/services/user_profile.rb
→ class UserProfile
app/services/user/profile_updater.rb
→ class User::ProfileUpdater
- One class per file, named correctly
- YAML functions must be whitelisted in
YamlFunctionRegistry
- Use Liquid templating for safe variable interpolation
- Validate all inputs before processing
- BDD approach: tests first, then implementation
- Comprehensive coverage required (edge cases, security validation)
- Use factories and test helpers in
spec/support/
- Single Source of Truth:
goals.md
(Epic → Story → Task structure)
- Current Status: Epic 2 complete (Core Data Model), Epic 3 in progress (API Interface)
- Documentation: Keep
README.md
current with architecture changes
- Rails 8.0.2 with Zeitwerk
- Liquid for secure templating
- RSpec testing framework
- SQLite with Solid adapters
- Hotwire (Stimulus + Turbo)
- React 18 for complex components
- Jest with Testing Library