# monarch-initiative/monarch-app architecture

> Architecture diagram of the GitHub repository monarch-initiative/monarch-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monarch-initiative/monarch-app
- Repository: https://github.com/monarch-initiative/monarch-app

## Overview

##### Project type and purpose
- This is a full-stack web application (“Monarch App”) comprising:
- A Vue.js single-page frontend (under `frontend/`) that runs in the browser.
- A Python library + FastAPI backend (`monarch_py` under `backend/src/…`) that exposes REST endpoints to drive the UI and also supports CLI tooling.
- A suite of adapters that connect the backend to multiple knowledge‐graph and NLP data stores (Solr, SQL, OAK triple store, spaCy).
- Infrastructure pieces (nginx reverse proxy, Dockerfiles, GitHub CI/CD workflows) to build, test, and deploy both tiers.

##### File structure
- Top-level: `.github/workflows/` (CI, build, test, deploy), `Makefile`, `mkdocs.yaml`, and `services/nginx/` for containerized deployment.
- `frontend/`: Vite-powered Vue 3 SPA with:
- `src/api/` modules that wrap each FastAPI endpoint.
- `src/components/`, `src/pages/`, and `src/router/` for UI structure.
- `e2e/` and `unit/` tests, plus Playwright & Vitest configs.
- `backend/`:
- `src/monarch_py/api/`: FastAPI routers, middleware.
- `src/monarch_py/service/`: business logic services (semsim, solr, curie).
- `src/monarch_py/interfaces/`: port definitions for search, entity, mapping, etc.
- `src/monarch_py/implementations/`: adapter (“hexagon”) modules for Solr, SQL, OAK, spaCy.
- `src/monarch_py/datamodels/`: pydantic schemas and YAML models.
- `cli.py` entrypoints for SQL and Solr command-line utilities.
- `tests/`: unit, integration, and API tests.
- `Dockerfile` + `start_api.sh` for containerized run.

##### README for additional insights
- Purpose: host an interactive UI over a massive biological knowledge graph, queryable via REST.
- Provides both a browser widget (Phenogrid) and a full standalone site.
- Encourages local dev via Docker, with scripted data‐generation and fixture tools under `scripts/`.

## Diagram (Mermaid)

```mermaid
graph TB
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CI["GitHub Actions Workflows"]:::infra
        Makefile["Makefile"]:::infra
        Mkdocs["mkdocs.yaml"]:::infra
    end
    CR["Docker Registry"]:::infra
    CI --> CR
    Makefile --> CR
    Mkdocs --> CR

    %% Client Tier
    subgraph "Client Tier"
        Browser["Browser (Vue SPA)"]:::frontend
    end
    click Browser "https://github.com/monarch-initiative/monarch-app/tree/main/frontend/"

    %% Edge Tier
    subgraph "Edge Tier"
        NginxMain["nginx Reverse Proxy"]:::edge
        NginxDocker["Dockerfile"]:::infra
        NginxConf["default.conf"]:::infra
    end
    click NginxDocker "https://github.com/monarch-initiative/monarch-app/tree/main/services/nginx/Dockerfile"
    click NginxConf "https://github.com/monarch-initiative/monarch-app/blob/main/services/nginx/config/default.conf"

    %% Application Tier
    subgraph "Application Tier"
        subgraph "Backend Container" style dashed
            API["FastAPI Router & Middleware"]:::applogic
            Service["Business Logic Services"]:::applogic
            Interfaces["Port Interfaces"]:::applogic
            DataModels["Data Models"]:::applogic
            subgraph "Adapters/Implementations"
                ImplsSolr["Solr Adapter"]:::applogic
                ImplsSQL["SQL Adapter"]:::applogic
                ImplsOAK["OAK Adapter"]:::applogic
                ImplsSpacy["spaCy Adapter"]:::applogic
            end
            subgraph "CLI Tools"
                CLIGeneral["cli.py"]:::applogic
                SolrCLI["solr_cli.py"]:::applogic
                SQLCLI["sql_cli.py"]:::applogic
            end
        end
    end
    click API "https://github.com/monarch-initiative/monarch-app/tree/main/backend/src/monarch_py/api/"
    click Service "https://github.com/monarch-initiative/monarch-app/tree/main/backend/src/monarch_py/service/"
    click Interfaces "https://github.com/monarch-initiative/monarch-app/tree/main/backend/src/monarch_py/interfaces/"
    click DataModels "https://github.com/monarch-initiative/monarch-app/tree/main/backend/src/monarch_py/datamodels/"
    click ImplsSolr "https://github.com/monarch-initiative/monarch-app/tree/main/backend/src/monarch_py/implementations/solr/"
    click ImplsSQL "https://github.com/monarch-initiative/monarch-app/tree/main/backend/src/monarch_py/implementations/sql/"
    click ImplsOAK "https://github.com/monarch-initiative/monarch-app/tree/main/backend/src/monarch_py/implementations/oak/"
    click ImplsSpacy "https://github.com/monarch-initiative/monarch-app/tree/main/backend/src/monarch_py/implementations/spacy/"
    click CLIGeneral "https://github.com/monarch-initiative/monarch-app/blob/main/backend/src/monarch_py/cli.py"
    click SolrCLI "https://github.com/monarch-initiative/monarch-app/blob/main/backend/src/monarch_py/solr_cli.py"
    click SQLCLI "https://github.com/monarch-initiative/monarch-app/blob/main/backend/src/monarch_py/sql_cli.py"

    %% Backend Docker
    BackendDocker["backend/Dockerfile"]:::infra
    click BackendDocker "https://github.com/monarch-initiative/monarch-app/tree/main/backend/Dockerfile"

    %% Data Tier
    subgraph "Data Tier"
        Solr["Apache Solr"]:::data
        SQL["PostgreSQL"]:::data
        OAK["OAK Triple Store"]:::data
        Spacy["spaCy NLP Models"]:::data
    end

    %% Interactions
    Browser --> NginxMain
    NginxMain --> API
    API --> Service
    Service --> Interfaces
    Interfaces --> ImplsSolr
    Interfaces --> ImplsSQL
    Interfaces --> ImplsOAK
    Interfaces --> ImplsSpacy
    ImplsSolr --> Solr
    ImplsSQL --> SQL
    ImplsOAK --> OAK
    ImplsSpacy --> Spacy
    CLIGeneral --> Service
    SolrCLI --> Service
    SQLCLI --> Service
    CR --> NginxDocker
    CR --> BackendDocker

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef edge fill:#E0F7FA,stroke:#006064,color:#006064
    classDef applogic fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef data fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
    classDef infra fill:#F5F5F5,stroke:#9E9E9E,color:#616161
```
