Amigos Unite

3) Domain Logic Layer (Service Objects + Invariants)

Complex workflows are implemented as service objects to preserve invariants and keep controllers thin:

• Events::CreateEvent
  • Creates the Event record
  • Creates the lead-coordinator connector
  • Normalizes speakers/performers inputs
  • Optionally triggers location creation/upsert when location attributes are provided
• Events::UpsertPrimaryLocation
  • Enforces exactly one primary location per event (DB constraints + service-level invariants)
  • Creates or updates EventLocation
  • Creates or updates the primary EventLocationConnector
  • Integrates with the location image persistence workflow
• Events::TransferLead
  • Performs an atomic lead coordinator reassignment
  • Updates connectors (demote old lead, promote new lead)
  • Updates event.lead_coordinator_id in the same transaction
  • Events::ChangeRole
  • Changes roles between participant and assistant coordinator
  • Explicitly rejects lead promotion (which must flow through the dedicated transfer-lead service)

Google Places integration is used as a real-world location intelligence layer, not merely as a convenience lookup.

Google APIs

• Google Places API
  • Validates venues using real-world records (place_id)
  • Retrieves canonical venue data (name, phone, structured address components where available)
  • Retrieves photo references representing Google Maps user-uploaded photos for a place
• Google Places Photos endpoint
  • Fetches images by photo_reference
  • The system selects a “best” image using rule-based heuristics (e.g., highest resolution / availability)
  • The selected image is persisted locally

Photo Selection + Persistence Pipeline

• Fetch candidate photos for a place_id
• Select one via deterministic heuristics
• Download server-side
• Persist locally via Active Storage
  • Media is controlled by the application (not hot-linked)
  • Attribution required by Google Places is persisted (e.g., location_image_attribution)
• The workflow is compatible with background execution to avoid blocking API requests:
  • Image processing and location image processing jobs support asynchronous handling

Data Model Invariants

• EventLocation stores structured address fields and place_id
• EventLocationConnector enforces:
  • Uniqueness of (event_id, event_location_id)
  • Uniqueness of the primary location per event (is_primary = true unique index)
• Image metadata and attribution are stored alongside the location record and/or attachment metadata.

PostgreSQL 17

• Relational store for core domain entities:
  • Amigos, Events, connectors, locations, JWT denylist, login activities
  • Data integrity is enforced at multiple levels:
• Rails validations (e.g., uniqueness constraints, invariants)
  • Database indexes and constraints (e.g., primary-location uniqueness, connector uniqueness)

PostGIS (optional / upgrade path)

• PostGIS is not required unless geospatial types/extensions are actively used.
• The design supports a future transition to true geospatial indexing/queries if location features expand.

Active Job + Background Workers

• Background-friendly architecture supports Sidekiq-compatible workloads such as:
  • Remote avatar fetch + processing
  • Location image processing (Google photo selection/download/attach)
  • Image normalization/resizing via image_processing + vips

Redis

• Primary backing store for Sidekiq job queues
• Also supports optional caching/rate limiting depending on production configuration

Docker + Docker Compose

• Containerized system components include:
  • Rails API container
  • PostgreSQL container
  • Redis container (for Sidekiq)
  • Sidekiq worker container (recommended separation from web)
• The architecture maintains clear separation of responsibilities:
  • Web process (Rails/Puma)
  • Worker process (Sidekiq)
  • Persistent volumes (DB data, logs, uploads as required)

GitHub Actions

• PR validation (backend-ci.yml)
  • Runs RSpec
  • Validates schema load and core invariants in CI
• Main branch pipeline (ghcr.yml)
  • Runs the test suite again as an authoritative gate
  • Builds a production Docker image
  • Pushes the image to GitHub Container Registry (GHCR) tagged as:
    • main
    • sha-<short>

GitHub Container Registry (GHCR)

• Stores immutable deployable Docker images
• The production VPS pulls images directly from GHCR

VPS Deployment

• VPS runtime environment includes Docker + Docker Compose
• Deployment flow:
  1. Merge to main triggers GHCR build + push
  2. VPS pulls the latest image tag (e.g., ghcr.io/sagacic-tim/amigos_unite_api:main)
  3. VPS runs docker compose up -d to recreate containers with the updated image
  4. Nginx (or similar) terminates TLS and reverse-proxies to the Rails container