How civis-vote/civis-api works
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