System Architecture - martinmendozadev/StateForce GitHub Wiki

🏗️ System Architecture

This page provides an overview of the StateForce system's architecture, its main components, and how they interact. The architecture is designed for reliability, scalability, and real-time emergency coordination across distributed agencies.

📌 Overview

StateForce is a web-based platform used by government agencies to manage emergency incidents, resources, and operational communication in real time.

  • Built as a modular monolith using Ruby on Rails.
  • Real-time updates powered by Hotwire (Turbo + Stimulus).
  • Designed for mobile-first field operations and centralized supervision.
  • Implements domain-driven design principles for maintainability and scalability.

🔗 View architecture diagram

🧩 Main Components

1. 🧠 Backend (Ruby on Rails)

  • Framework: Rails 8 with API and HTML rendering.
  • Key Responsibilities:
    • Business logic
    • Role-based access control
    • Resource allocation
    • Incident tracking
    • Audit logging
  • Main Services:
    • IncidentManager – Handles creation and updates of emergency incidents.
    • ResourceDispatcher – Assigns units based on availability and proximity.
    • NotificationService – Sends real-time updates via Turbo or external channels.

2. 🗄️ Database (PostgreSQL)

  • Relational DB with normalized structure.
  • Core entities:
    • users, roles, units, incidents, hospitals, reports, messages
  • Features:
    • Ensures data consistency through foreign key constraints.
    • Indexes for optimized queries (e.g., incident lookups).
    • Audit logs for tracking sensitive operations.

For more details, visit Database Wiki

3. 🖥️ Frontend (Hotwire + TailwindCSS)

  • Technology Stack:
    • Server-rendered views enhanced with Turbo Streams and StimulusJS.
    • Responsive design using TailwindCSS utility classes.
  • Frontend Features:
    • Turbo Streams provide dynamic UI updates without manual WebSocket handling.
    • StimulusJS controllers modularize behavior (e.g., filters, modals, maps).
    • Accessible design compliant with WCAG 2.1.

4. ⚙️ Asynchronous Processing (Sidekiq + Redis)

  • Purpose: Handles background jobs like email delivery, report generation, and geolocation processing.
  • Queue Manager: Redis for queue management and pub/sub messaging.
  • Examples of Jobs:
    • NotifySupervisorJob – Sends notifications to supervisors.
    • GenerateIncidentPDFJob – Generates printable reports for incidents.
    • SyncHospitalDataJob – Updates hospital data periodically.

5. 🔐 Authentication & Authorization

  • Authentication: Devise (email/password), with support for Google OAuth2 via OmniAuth.
  • Authorization:
    • Pundit for policy-based access control.
    • Centralized Role model defines system access rules.
  • Security Features:
    • Email confirmation required before accessing protected routes.
    • Session timeout and auto-logout enforced to maintain security.

6. 🌐 External Integrations

  • APIs:
    • Emergency hospitals dataset via ArcGIS REST API (read-only integration).
    • [Planned] Weather or alert systems via civil protection APIs.
  • OAuth2:
    • Google SSO for government accounts.
  • Webhooks:
    • Future support for outgoing event hooks to agency dashboards.

🔁 Data Flow

Emergency Resource Allocation

sequenceDiagram
  participant User
  participant UI
  participant Rails API
  participant DB
  participant Sidekiq

  User->>UI: Report Incident
  UI->>Rails API: POST /incidents
  Rails API->>DB: Create record
  Rails API->>Sidekiq: Trigger ResourceAssignmentJob
  Sidekiq->>DB: Update unit status
  Rails API->>UI: Turbo Stream - Update Incident Feed

User Login & Role Verification

sequenceDiagram
  participant User
  participant Devise
  participant DB
  participant Pundit

  User->>Devise: Login (email + password)
  Devise->>DB: Authenticate
  Devise->>Pundit: Check user role
  Pundit->>UI: Allow/deny access

🚀 Deployment Architecture

  • App Server: Puma (multi-threaded Rails server).
  • Background Jobs: Sidekiq workers managed via systemd or Procfile.
  • Redis: In-memory job queue and pub/sub messaging.
  • PostgreSQL: Main relational database with active backups.
  • Cloudinary CDN: Used for assets and pre-rendered documents.
  • Environments:
    • production – Live system for users.
    • staging – Internal QA and testing.
    • development – Local machine with seeded data.

🔒 Security Considerations

  • HTTPS enforced on all environments.
  • Encrypted credentials using config/credentials.yml.enc.
  • Audit Logs: Track sensitive actions (e.g., login attempts, role changes, resource reassignments).
  • Rate Limiting: Prevent abuse of APIs and endpoints.
  • CSRF Protection: Enabled for all forms and requests.
  • Content Security Policy (CSP): Configured headers to block unauthorized scripts.

📂 Additional Resources

💡 Proposals for Architecture Changes:
Submit a pull request or initiate a discussion for any major updates.