# hospitalrun/hospitalrun-server architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Node.js‐based backend service implementing a GraphQL API for the HospitalRun full-stack hospital management application.
- It serves as the data layer and business logic layer, exposing health checks and domain resolvers, persisting data in CouchDB/PouchDB.

##### File Structure
- Top‐level folders:
- `src/` – Application source:
– `app.ts` defines the Express/HTTP server and GraphQL middleware
– `index.ts` entry point bootstrapping the app
– `graphql/` holds `schema.ts` (type definitions) and `resolvers.ts` (resolver functions)
– `services/` contains discrete service modules (`health.ts`, `root.ts`) encapsulating business logic
- `bin/ddoc.js` – CLI tool to generate CouchDB design documents
- `db/` – local development database config (`config.json`) for pouchdb‐server
- `docker-compose.yml` – spins up the Node server and a dev PouchDB instance
- `test/` – tests using node-tap against service modules
- Configuration files:
- `.env.example` + `dotenv` for environment variables
- TypeScript configs in `tsconfig.json`
- Linting/prettier/CI configs under `.github/` and root

##### README Insights
- Confirms GraphQL over HTTP, PouchDB‐server in development and CouchDB in production.
- Encourages Docker Compose for local dev.

##### Core Components
a. **API Layer**
- HTTP/Express server (app.ts)
- GraphQL endpoint
b. **Business Logic Layer**
- GraphQL Resolvers (resolvers.ts)
- Service modules (health.ts, root.ts, plus future domain services)
c. **Data Layer**
- PouchDB‐server (development) or CouchDB (production)
- `db/config.json` for DB endpoints & credentials
d. **Dev Tooling & Infrastructure**
- `docker-compose` orchestration: Node.js container ↔ PouchDB container
- CLI script (`bin/ddoc.js`) for design docs generation
- Test runner (node-tap) exercising services

##### Relationships and Data Flows
- Client (e.g., HospitalRun Frontend) → HTTP POST to `/graphql` → Express
- Express → GraphQL engine → Resolver
- Resolver → Service layer → DB driver → PouchDB/CouchDB
- Health check service → `/health` HTTP endpoint
- Docker Compose network between containers (Node ↔ PouchDB)

##### Architectural Patterns
- **Layered Architecture**:
Presentation (HTTP/GraphQL) → Business (services) → Data (CouchDB)
- **Modularity**: Distinct service modules for separation of concerns
- **12-factor app**: uses environment variables, externalized config, single codebase

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["HospitalRun Frontend"]:::external
    Client -->|HTTP POST /graphql| Express

    %% Application Code Layer
    subgraph "Application Code" 
        direction TB
        Express["Express Server (app.ts)"]:::app
        Bootstrap["Application Bootstrap (index.ts)"]:::app
        Schema["GraphQL Schema (schema.ts)"]:::app
        Resolvers["GraphQL Resolvers (resolvers.ts)"]:::app
        HealthService["Health Service Module (health.ts)"]:::app
        RootService["Root Service Module (root.ts)"]:::app
    end

    Express -->|initializes| Bootstrap
    Express -->|uses GraphQL middleware| Schema
    Schema -->|provides types| Resolvers
    Resolvers -->|executes business logic| HealthService
    Resolvers -->|executes business logic| RootService

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DBConfig["DB Config (db/config.json)"]:::data
        Database["PouchDB (dev) / CouchDB (prod)"]:::data
    end

    HealthService -->|reads/writes| DBConfig
    RootService -->|reads/writes| DBConfig
    DBConfig -->|connects to| Database

    %% Dev Tools & Infrastructure
    subgraph "Dev Tools & Infrastructure"
        direction TB
        DockerCompose["Docker Compose (docker-compose.yml)"]:::tool
        CLI["Design Docs CLI (bin/ddoc.js)"]:::tool
        TestHealth["Health Service Tests (test/services/health.test.ts)"]:::tool
        TestHelper["Test Helpers & Config (test/helper.ts, test/tsconfig.json)"]:::tool
    end

    DockerCompose -->|orchestrates| Express
    DockerCompose -->|orchestrates| Database
    CLI -->|generates design docs| Database
    TestHealth -->|tests| HealthService
    TestHelper -->|supports tests| TestHealth

    %% Click Events
    click Express "https://github.com/hospitalrun/hospitalrun-server/blob/master/src/app.ts"
    click Bootstrap "https://github.com/hospitalrun/hospitalrun-server/blob/master/src/index.ts"
    click Schema "https://github.com/hospitalrun/hospitalrun-server/blob/master/src/graphql/schema.ts"
    click Resolvers "https://github.com/hospitalrun/hospitalrun-server/blob/master/src/graphql/resolvers.ts"
    click HealthService "https://github.com/hospitalrun/hospitalrun-server/blob/master/src/services/health.ts"
    click RootService "https://github.com/hospitalrun/hospitalrun-server/blob/master/src/services/root.ts"
    click DBConfig "https://github.com/hospitalrun/hospitalrun-server/blob/master/db/config.json"
    click DockerCompose "https://github.com/hospitalrun/hospitalrun-server/blob/master/docker-compose.yml"
    click CLI "https://github.com/hospitalrun/hospitalrun-server/blob/master/bin/ddoc.js"
    click TestHealth "https://github.com/hospitalrun/hospitalrun-server/blob/master/test/services/health.test.ts"
    click TestHelper "https://github.com/hospitalrun/hospitalrun-server/blob/master/test/helper.ts"

    %% Styles
    classDef app fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef data fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef tool fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:1px;
```
