System Architecture

🏗️ 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 using Hotwire (Turbo + Stimulus).
• Designed for mobile-first field operations and centralized supervision.
• Follows domain-driven design principles for maintainability.

🔗 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

For more info visit Database Wiki

3. 🖥️ Frontend (Hotwire + TailwindCSS)

• Built with server-rendered views and enhanced with Turbo and Stimulus.
• Responsive design using TailwindCSS utility classes.
• Turbo Streams provide real-time UI updates without needing WebSockets manually.
• Stimulus controllers modularize behavior (filters, modals, maps, etc.).

4. ⚙️ Asynchronous Processing (Sidekiq + Redis)

• Handles background jobs (email delivery, report generation, geolocation processing).

• Redis acts as the queue broker.

• Jobs are retried automatically on failure.

• Examples:

  • NotifySupervisorJob
  • GenerateIncidentPDFJob
  • SyncHospitalDataJob

5. 🔐 Authentication & Authorization

• Authentication: Devise (email/password), with support for Google OAuth2 via OmniAuth.

• Authorization:

  • Pundit for policy-based access.
  • Centralized Role model defining system access.

• Email confirmation required before accessing protected routes.

• Session timeout and auto-logout enforced for security.

6. 🌐 External Integrations

• APIs:

  • Emergency hospitals dataset via ArcGIS REST API (read-only).
  • [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

Loading

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

Loading

---

🚀 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

• PostgreSQL: Main relational DB

• Cloudinary CDN: For assets and pre-rendered documents

• Environments:

  • production – live system
  • staging – internal QA and tests
  • development – local machine with seeded data

---

🔒 Security Considerations

• HTTPS enforced on all environments.
• Encrypted credentials using config/credentials.yml.enc.
• Audit Logs for sensitive actions (login, role changes, resource reassignment).
• Rate limiting and CSRF protection enabled.
• Content Security Policy (CSP) headers configured.

---

📂 Additional Resources

• Role Access Policy
• Flow Diagrams
• StateForce Design System

---

Need to propose changes to architecture? Please submit a PR or init a discussion.