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 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

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 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

• Role Access Policy
• Flow Diagrams
• StateForce Design System

---

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