Architecture - FaqiangMei/MHA-Survey-Portal GitHub Wiki

Architecture

This page summarizes how the portal is assembled across the stack so contributors can trace a feature from UI to infrastructure.

High-Level Diagram

Browser (Students/Advisors/Admins)
       ↓
Rails (Controllers, Turbo, ActionCable)
       ↓
Services & Jobs (SurveyAssignments::*, Reports::*, Notification jobs)
       ↓
PostgreSQL + Redis (state, cache, queues)
       ↓
Storage (ActiveStorage S3 / Google Drive evidence)

Application Layers

Layer Responsibilities Notable Components
Presentation ERB templates, Tailwind-based styling, Stimulus controllers for inline interactions. app/views, app/assets/stylesheets/application.css, app/javascript/controllers/*
Domain / Services Survey assignment logic, reporting/composite exports, notification orchestration. app/services/survey_assignments/*, Reports::DataAggregator, CompositeReportGenerator
Persistence ActiveRecord models backed by PostgreSQL schemas for surveys, users, notifications, and audit logs. app/models, db/schema.rb, db/migrate/*
Background Jobs Queue-heavy work such as reminders, report exports, evidence checks. SurveyNotificationJob, CompositeReportJob, config/queue.yml
Integrations Google OAuth (Devise + OmniAuth), Google Drive evidence validation, S3/MinIO for ActiveStorage. config/initializers/devise.rb, EvidenceController, storage.yml

Environments

  • Development: Docker Compose with web, db, and queue services. bin/dev starts Rails + Vite/Propshaft pipeline.
  • Test: Uses the same containers; CI workflow (.github/workflows/ci.yml) installs dependencies, runs RuboCop, and executes Rails tests.
  • Production: Heroku by default (see Heroku Guide); supports container deployments via Kamal.

Key Data Flows

  1. Survey lifecycle — Admin or advisor creates a survey → assignments generated → students complete responses → feedback captured → analytics aggregated.
  2. Notifications — Stateful reminders stored in Notification table; ActionMailer + optional email provider deliver copies; in-app banner surfaces via NotificationsController.
  3. Evidence handling — Students upload Drive links → EvidenceController#check_access validates permissions → attachments stored through ActiveStorage while referencing Drive IDs.

Observability

  • Lograge formats JSON logs for ingestion into LogDNA/Splunk.
  • ApplicationController tags requests with role + survey context for traceability.
  • Admin dashboard surfaces queue latency, job retries, and recent audit entries.

References