# civis-vote/civis-api architecture

> Architecture diagram of the GitHub repository civis-vote/civis-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/civis-vote/civis-api
- Repository: https://github.com/civis-vote/civis-api

## Overview

##### Project type and purpose
- This is a monolithic Ruby on Rails application that exposes a public GraphQL API and also serves server-rendered UI (admin panels, organisation dashboards, public pages).
- Its primary purpose is to act as a bridge between citizens and governments, allowing users to sign up, submit consultation responses, view analytics, and manage administrative data via GraphQL and HTML views.

##### File structure for architectural cues
- Top-level folders:
- app/controllers, app/views, app/assets – classic Rails MVC for server-rendered pages
- app/graphql – GraphQL schema, queries, mutations and type definitions for API layer
- app/jobs, config/sidekiq.yml, config/schedule.rb – background processing with ActiveJob + Sidekiq
- config/routes.rb, config/cable.yml – HTTP routing and WebSocket (ActionCable)
- config/storage.yml – ActiveStorage integration with AWS S3
- Config files: database.yml (PostgreSQL), redis (via sidekiq.yml), cable, credentials for OAuth, Postmark, AWS, Scout APM
- Deployment: Cloud66 manifests and Procfile (Puma web server, Sidekiq workers)

##### Key architecture notes from README
- Public GraphQL endpoint at /graphql, authenticated via access_token in HTTP Authorization header
- UIs (www.civis.vote and other clients) consume the GraphQL API or use the server-rendered views
- Third-party integrations: Postmark (emails), AWS S3 (file storage), Facebook/Google OAuth, Scout APM, Errbit, Redis (Sidekiq queue), PostgreSQL

a. Main components to show
- Clients: Web browsers (HTML UI), GraphQL clients (Postman, mobile apps, JS frontends)
- Rails Monolith:
- Web/API Layer: Puma web processes handling HTTP/GraphQL requests, ActionCable for real-time channels
- GraphQL Engine: Schema, queries, mutations, resolvers under app/graphql
- MVC Layer: Controllers, Views, Assets for server-rendered pages and static resources
- Background Workers: Sidekiq processes executing ActiveJob jobs (email, exports, notifications)
- Datastores and Caches: PostgreSQL database, Redis (job queue, caching)
- File Storage: AWS S3 via ActiveStorage
- External Services:
- OAuth Providers (Google, Facebook)
- Email Service (Postmark)
- Error & Performance Monitoring (Errbit, Scout APM)
b. Relationships & interactions
- Web/API Layer reading/writing to PostgreSQL and Redis
- ActiveJob enqueued in Redis and processed by Sidekiq workers
- Rails pushing file uploads to S3 and retrieving from S3
- Rails sending emails via Postmark API
- Rails contacting OAuth providers for login flows
- ActionCable WebSocket channel between Clients and Rails
c. Architectural patterns & principles
- Monolithic MVC with clear separation: API (GraphQL) vs. UI (Rails views) vs. background processing
- Use of GraphQL facade to unify data access, backed by ActiveRecord models
- Asynchronous processing via Sidekiq for long-running tasks (exports, notifications)
- Service integrations abstracted behind initializer configurations
- Use of concerns and modular directory structure under app/ for maintainability
d. Key technologies & libraries
- Ruby on Rails 7, Puma, ActiveRecord, ActiveStorage
- GraphQL Ruby (app/graphql)
- Devise & devise_invitable for authentication
- Sidekiq for background jobs, Redis as queue store
- AWS S3 for attachments, Postmark for email, OAuth gems for social login
- Scout APM & Errbit for observability

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients
    subgraph "Clients"
        Browser["Web Browser UI"]:::client
        APIClient["GraphQL Client"]:::client
    end

    %% Rails Monolith
    subgraph "Rails Monolith"
        %% Web/API Layer
        subgraph "Web/API Layer"
            Puma["Puma Web/API"]:::app
            Routing["HTTP Router"]:::app
            CableServer["ActionCable WebSocket"]:::app
        end

        %% GraphQL Layer
        subgraph "GraphQL Layer"
            Schema["Schema"]:::app
            Queries["Queries"]:::app
            Mutations["Mutations"]:::app
            Types["Types"]:::app
        end

        %% MVC Layer
        subgraph "MVC Layer"
            Controllers["Controllers"]:::app
            Views["Views"]:::app
            Assets["Assets"]:::app
            JS["JavaScript"]:::app
        end

        %% Background Processing
        subgraph "Background Processing"
            Jobs["ActiveJob Jobs"]:::app
            SidekiqProcess["Sidekiq Workers"]:::app
        end

        %% File Storage Integration
        subgraph "File Storage Integration"
            StorageConf["storage.yml"]:::app
            Uploader["Image Uploader"]:::app
            ShrineInit["Shrine Initializer"]:::app
        end
    end

    %% Datastores
    subgraph "Datastores"
        Postgres["PostgreSQL"]:::db
        Redis["Redis (Cache & Queue)"]:::cache
        S3["AWS S3"]:::storage
    end

    %% External Services
    subgraph "External Services"
        OAuthProviders["OAuth Providers"]:::external
        Postmark["Postmark Email"]:::external
        Scout["Scout APM"]:::external
        Errbit["Errbit"]:::external
    end

    %% Connections
    Browser -->|HTTPS| Puma
    APIClient -->|POST /graphql| Puma
    Puma -->|routes requests| Routing
    Routing -->|dispatch to| Schema
    Routing -->|dispatch to| Controllers
    Schema -->|resolves via| Queries
    Schema -->|resolves via| Mutations
    Queries -->|uses| Types
    Mutations -->|uses| Types
    Controllers -->|renders| Views
    Views -->|delivers HTML| Browser
    Controllers -->|serves assets| Assets
    Controllers -->|serves JS| JS
    Browser -->|WebSocket /cable| CableServer
    CableServer -->|push updates| Browser

    Puma -->|read/write| Postgres
    Puma -->|cache| Redis
    Puma -->|enqueue jobs| Redis
    SidekiqProcess -->|dequeue jobs| Redis
    SidekiqProcess -->|executes| Jobs
    SidekiqProcess -->|read/write| Postgres

    Puma -->|upload/download| S3
    Uploader -->|stores files| S3

    Puma -->|send email| Postmark
    Puma -->|oauth login| OAuthProviders
    Puma -->|report errors| Errbit
    Puma -->|report perf| Scout

    %% Click Events
    click Puma "https://github.com/civis-vote/civis-api/tree/main/Procfile"
    click Puma "https://github.com/civis-vote/civis-api/blob/main/config/puma.rb"
    click Routing "https://github.com/civis-vote/civis-api/blob/main/config/routes.rb"
    click CableServer "https://github.com/civis-vote/civis-api/blob/main/config/cable.yml"
    click CableServer "https://github.com/civis-vote/civis-api/blob/main/app/channels/application_cable/connection.rb"
    click CableServer "https://github.com/civis-vote/civis-api/blob/main/app/channels/application_cable/channel.rb"
    click Schema "https://github.com/civis-vote/civis-api/blob/main/app/graphql/civis_api_schema.rb"
    click Queries "https://github.com/civis-vote/civis-api/tree/main/app/graphql/queries"
    click Mutations "https://github.com/civis-vote/civis-api/tree/main/app/graphql/mutations"
    click Types "https://github.com/civis-vote/civis-api/tree/main/app/graphql/types"
    click Controllers "https://github.com/civis-vote/civis-api/tree/main/app/controllers"
    click Views "https://github.com/civis-vote/civis-api/tree/main/app/views"
    click Assets "https://github.com/civis-vote/civis-api/tree/main/app/assets"
    click JS "https://github.com/civis-vote/civis-api/tree/main/app/javascript"
    click Jobs "https://github.com/civis-vote/civis-api/tree/main/app/jobs"
    click SidekiqProcess "https://github.com/civis-vote/civis-api/blob/main/config/sidekiq.yml"
    click SidekiqProcess "https://github.com/civis-vote/civis-api/blob/main/config/initializers/sidekiq.rb"
    click Jobs "https://github.com/civis-vote/civis-api/blob/main/config/schedule.rb"
    click StorageConf "https://github.com/civis-vote/civis-api/blob/main/config/storage.yml"
    click Uploader "https://github.com/civis-vote/civis-api/blob/main/app/models/image_uploader.rb"
    click ShrineInit "https://github.com/civis-vote/civis-api/blob/main/config/initializers/shrine.rb"
    click Controllers "https://github.com/civis-vote/civis-api/blob/main/config/initializers/devise.rb"
    click Controllers "https://github.com/civis-vote/civis-api/blob/main/config/initializers/omniauth.rb"
    click Controllers "https://github.com/civis-vote/civis-api/blob/main/app/controllers/sessions_controller.rb"
    click Controllers "https://github.com/civis-vote/civis-api/blob/main/app/controllers/oauth_controller.rb"
    click Views "https://github.com/civis-vote/civis-api/tree/main/app/views/devise/"
    click Postmark "https://github.com/civis-vote/civis-api/blob/main/app/mailers/user_mailer.rb"
    click Postmark "https://github.com/civis-vote/civis-api/blob/main/app/mailers/spotlight_search/export_mailer.rb"
    click Errbit "https://github.com/civis-vote/civis-api/blob/main/config/initializers/errbit.rb"
    click Scout "https://github.com/civis-vote/civis-api/blob/main/config/scout_apm.yml"
    click Postgres "https://github.com/civis-vote/civis-api/blob/main/config/database.yml"
    click Redis "https://github.com/civis-vote/civis-api/blob/main/config/sidekiq.yml"
    click Tasks "https://github.com/civis-vote/civis-api/tree/main/lib/tasks"
    click CloudManifest "https://github.com/civis-vote/civis-api/blob/main/.cloud66/manifest.yml"
    click CloudManifest "https://github.com/civis-vote/civis-api/blob/main/.cloud66/deploy_hooks.yml"

    %% Styles
    classDef client fill:#f3e5f5,stroke:#7e57c2
    classDef app fill:#bbdefb,stroke:#1e88e5
    classDef db fill:#c8e6c9,stroke:#388e3c
    classDef cache fill:#dcedc8,stroke:#558b2f
    classDef storage fill:#b3e5fc,stroke:#0288d1
    classDef external fill:#ffe0b2,stroke:#f57c00
```
