# griffithlab/civic-server architecture

> Architecture diagram of the GitHub repository griffithlab/civic-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/griffithlab/civic-server
- Repository: https://github.com/griffithlab/civic-server

## Overview

##### Project type and purpose
- This is a full-stack Rails “server” application that acts as the backend for the CIViC (Clinical Interpretations of Variants in Cancer) platform.
- It exposes JSON APIs consumed by an AngularJS frontend (in a separate repo), and provides an admin interface (ActiveAdmin).
- It also runs ETL/import pipelines and background jobs to ingest external data, generate TSV/VCF exports, and send notifications.

##### File structure
- app/
- controllers/ → HTTP & API endpoints (RESTful controllers + custom controllers such as typeahead_searches, ga4gh)
- models/ → domain objects (Assertion, EvidenceItem, Gene, Variant, Subscription, Notification, etc.)
- views/ & assets/ → Rails-served HTML for admin + precompiled Angular assets (public/), CSS/JS via the asset pipeline
- admin/ → ActiveAdmin DSL definitions for the built-in admin UI
- jobs/ → Delayed::Job worker definitions for background processing (data import, dump generation, notifications)
- api_helpers/, concerns/, presenters/, policies/ → modules and service objects implementing cross-cutting concerns (auth, rate limiting, Pundit policies, serializers)
- lib/importer/ & lib/scrapers/ → ETL code to fetch and transform external data (PubMed, NCI Thesaurus, ClinicalTrials, MyGeneInfo, etc.)
- config/ → Rails configuration, routes.rb, scheduled_tasks.yml (cron jobs), Dockerfile & docker-compose.yml (containerization)
- db/ → migrations, seeds, views, schema and structure SQL
- public/ → pre-built Angular single-page app, Bower components, static download archives
- spec/ → RSpec test suite covering controllers, models, jobs, policies
- misc_scripts/ → one-off scripts for data backfills and external integrations

##### Pulling in README insights
- Rails ≥2.1 on Postgres, Node/Bower/Gulp for the client.
- Background workers via bin/delayed_job (Delayed::Worker).
- Frontend served independently on port 3001 in dev, Rails on 3000.
- The server already bundles the production frontend build under public/.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier"
        direction TB
        Browser["Web Browser"]:::client
        Angular["AngularJS Frontend"]:::client
        ThirdPartyClients["Third-Party API Consumers"]:::client
    end

    %% Application Tier
    subgraph "Web Application Tier"
        direction TB
        RailsServer["Rails API Server (Puma/Unicorn)"]:::app
        Controllers["Controllers & API Endpoints"]:::app
        AdminUI["ActiveAdmin Admin Interface"]:::app
        Middleware["Rack Middleware (CORS, Rack::Attack)"]:::app
        Assets["Asset Pipeline & Static Assets"]:::app
        Policies["Pundit Policies"]:::app
        Services["Service Objects & Concerns"]:::app
    end

    %% Persistence Tier
    subgraph "Persistence Tier"
        direction TB
        Postgres["PostgreSQL DB"]:::db
        DBViews["Database Reporting Views"]:::db
    end

    %% Background Processing Tier
    subgraph "Background Processing Tier"
        direction TB
        JobQueue["DelayedJob Worker Pool"]:::background
        ETL["ETL Import Pipelines"]:::background
        TSVJobs["TSV/VCF Generation Jobs"]:::background
        EmailJobs["Email Notification Jobs"]:::background
        NDExJob["NDEx Network Upload Job"]:::background
    end

    %% External Integrations Tier
    subgraph "External Services & Integrations"
        direction TB
        ExternalAPIs["External HTTP APIs"]:::external
        ORCID["ORCID API Helper"]:::external
        S3["AWS S3 Uploads"]:::external
        EmailService["Email/SMTP Service"]:::external
    end

    %% DevOps / Deployment
    subgraph "DevOps / Deployment"
        direction TB
        Docker["Docker Configuration"]:::devops
        Capistrano["Capistrano Deployment Scripts"]:::devops
    end

    %% Connections
    Browser -->|API calls & static asset requests| RailsServer
    Angular -->|API calls| RailsServer
    RailsServer -->|reads/writes| Postgres
    RailsServer -->|enqueue jobs| JobQueue
    JobQueue -->|jobs use DB| Postgres
    JobQueue -->|calls external APIs| ExternalAPIs
    JobQueue -->|uploads artifacts| S3
    JobQueue -->|sends notifications| EmailService
    ETL <--> ExternalAPIs
    RailsServer -->|serves static files| Assets
    Docker -->|deploys new build| RailsServer
    Capistrano -->|deploys code| RailsServer

    %% Component relationships inside Application Tier
    RailsServer --> Controllers
    RailsServer --> AdminUI
    RailsServer --> Middleware
    RailsServer --> Assets
    RailsServer --> Policies
    RailsServer --> Services

    %% Styling
    classDef client fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef app fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef db fill:#FFE0B2,stroke:#F57C00,color:#E65100;
    classDef background fill:#E1BEE7,stroke:#8E24AA,color:#4A148C;
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#455A64;
    classDef devops fill:#F5F5F5,stroke:#BDBDBD,color:#424242;

    %% Click Events
    click Angular "https://github.com/griffithlab/civic-server/tree/staging/public/scripts/"
    click Angular "https://github.com/griffithlab/civic-server/tree/staging/public/styles/"
    click Angular "https://github.com/griffithlab/civic-server/tree/staging/public/bower_components/"
    click Controllers "https://github.com/griffithlab/civic-server/tree/staging/app/controllers/"
    click Controllers "https://github.com/griffithlab/civic-server/blob/staging/config/routes.rb"
    click AdminUI "https://github.com/griffithlab/civic-server/tree/staging/app/admin/"
    click Middleware "https://github.com/griffithlab/civic-server/tree/staging/app/middleware/"
    click Middleware "https://github.com/griffithlab/civic-server/blob/staging/config/initializers/cors.rb"
    click Middleware "https://github.com/griffithlab/civic-server/blob/staging/config/initializers/rack_attack.rb"
    click Assets "https://github.com/griffithlab/civic-server/tree/staging/app/assets/"
    click Assets "https://github.com/griffithlab/civic-server/tree/staging/public/assets/"
    click JobQueue "https://github.com/griffithlab/civic-server/tree/staging/app/jobs/"
    click JobQueue "https://github.com/griffithlab/civic-server/tree/staging/bin/delayed_job"
    click JobQueue "https://github.com/griffithlab/civic-server/blob/staging/config/scheduled_tasks.yml"
    click Postgres "https://github.com/griffithlab/civic-server/tree/staging/db/migrate/"
    click Postgres "https://github.com/griffithlab/civic-server/blob/staging/db/schema.rb"
    click Postgres "https://github.com/griffithlab/civic-server/blob/staging/db/structure.sql"
    click ETL "https://github.com/griffithlab/civic-server/tree/staging/lib/importer/"
    click ETL "https://github.com/griffithlab/civic-server/tree/staging/lib/scrapers/"
    click ORCID "https://github.com/griffithlab/civic-server/blob/staging/app/api_helpers/orcid_api.rb"
    click S3 "https://github.com/griffithlab/civic-server/blob/staging/config/initializers/aws_s3.rb"
    click NDExJob "https://github.com/griffithlab/civic-server/blob/staging/app/jobs/upload_network_to_ndex.rb"
    click TSVJobs "https://github.com/griffithlab/civic-server/blob/staging/app/jobs/create_civic_vcfs.rb"
    click TSVJobs "https://github.com/griffithlab/civic-server/blob/staging/app/jobs/generate_tsvs.rb"
    click TSVJobs "https://github.com/griffithlab/civic-server/blob/staging/app/jobs/create_monthly_civic_vcfs.rb"
    click TSVJobs "https://github.com/griffithlab/civic-server/blob/staging/app/jobs/create_nightly_civic_vcfs.rb"
    click EmailJobs "https://github.com/griffithlab/civic-server/blob/staging/app/jobs/notify_subscribers.rb"
    click EmailJobs "https://github.com/griffithlab/civic-server/blob/staging/app/jobs/notify_mentioned.rb"
    click Policies "https://github.com/griffithlab/civic-server/tree/staging/app/policies/"
    click Services "https://github.com/griffithlab/civic-server/tree/staging/app/controllers/concerns/"
    click Services "https://github.com/griffithlab/civic-server/tree/staging/app/models/actions/"
    click Services "https://github.com/griffithlab/civic-server/tree/staging/app/presenters/"
    click Services "https://github.com/griffithlab/civic-server/tree/staging/app/api_helpers/"
    click DBViews "https://github.com/griffithlab/civic-server/blob/staging/db/views/evidence_items_by_statuses_v01.sql"
    click DBViews "https://github.com/griffithlab/civic-server/blob/staging/db/views/evidence_items_by_statuses_v02.sql"
    click Docker "https://github.com/griffithlab/civic-server/tree/staging/Dockerfile"
    click Docker "https://github.com/griffithlab/civic-server/blob/staging/docker-compose.yml"
    click Docker "https://github.com/griffithlab/civic-server/blob/staging/docker-entrypoint.sh"
    click Capistrano "https://github.com/griffithlab/civic-server/tree/staging/Capfile"
    click Capistrano "https://github.com/griffithlab/civic-server/tree/staging/lib/capistrano/tasks/"
    click Capistrano "https://github.com/griffithlab/civic-server/blob/staging/config/deploy/*.rb"
```
