# helpwave/services architecture

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

- Interactive diagram: https://gitdiagram.com/helpwave/services
- Repository: https://github.com/helpwave/services

## Overview

##### Main Components

a. Services Layer:
- user-svc (User management and organizations)
- tasks-svc (Task management, wards, rooms, beds, patients)
- property-svc (Property management)
- updates-svc (Real-time updates)

b. API Gateway:
- APISIX (Handles both gRPC-web and gRPC proxy)
- Ports: 9080 (HTTP), 9433 (HTTPS), 9090 (control API)

c. Infrastructure Components:
- PostgreSQL (Database)
- Redis (Caching/PubSub)
- EventStoreDB (Event sourcing)
- SpiceDB (Authorization)
- Jaeger (Distributed tracing)

d. Communication Layer:
- Dapr (Service mesh/sidecar)
- gRPC (Inter-service communication)
- gRPC-web (Client-facing API)

**┌─────────────────────────────────────────────┐**
- Client Layer (Web/Mobile)                   │
- ┤
- Gateway Layer (APISIX + Dapr)              │
- ┤
- Services Layer (Microservices)              │
- ┤
- Infrastructure Layer (Databases/Storage)    │
- ┘

##### Key Relationships to Highlight

a. Service Communication:
- Dapr sidecars next to each service
- GRPC communication between services
- Event sourcing patterns with EventStoreDB

b. Data Flow:
- Client requests through APISIX
- Service-to-service communication via Dapr
- Database connections
- Event streams

##### Specific Implementation Details

**┌──────────────────────────────────────────────────────────────┐**
- Clients (Web/Mobile)                                         │
- ┬────────────────────────────────────────┘
- ▼
**┌──────────────────────────────────────────────────────────────┐**
- APISIX Gateway (gRPC-web/gRPC)                              │
- ┬────────────────────────────────────────┘
- ▼
**┌──────────────────────────────────────────────────────────────┐**
- Dapr Service Mesh                                            │
- ┬──────────┬───────────┬──────────────┬────────────┤
- user-svc │tasks-svc │updates-svc│ property-svc │ Other svcs │
- ┴──────────┴───────────┴──────────────┴────────────┘
- ▲
**┌─────────────────────┴───────────────────────────────────────┐**
- Infrastructure                                              │
- ┬────────────┬────────────┬────────────┬────────┤
- PostgreSQL │   Redis    │EventStoreDB│  SpiceDB   │ Jaeger │
- ┴────────────┴────────────┴────────────┴────────┘

##### Additional Elements

- Port numbers for each service
- Authentication flow
- Event sourcing patterns
- Monitoring and tracing paths
- Development vs. production components

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        WebClient["Web Client"]
        MobileClient["Mobile Client"]
    end

    subgraph Gateway
        APISIX["API Gateway (APISIX)"]:::gateway
        click APISIX "https://github.com/helpwave/services/tree/main/apisix"
    end

    subgraph ServiceMesh
        Dapr["Dapr Service Mesh"]:::mesh
        click Dapr "https://github.com/helpwave/services/tree/main/dapr"
        click Dapr "https://github.com/helpwave/services/blob/main/dapr/config.yaml"
    end

    subgraph Services
        UserSvc["User Service"]:::service
        TasksSvc["Tasks Service"]:::service
        PropertySvc["Property Service"]:::service
        UpdatesSvc["Updates Service"]:::service
        
        click UserSvc "https://github.com/helpwave/services/tree/main/services/user-svc"
        click TasksSvc "https://github.com/helpwave/services/tree/main/services/tasks-svc"
        click PropertySvc "https://github.com/helpwave/services/tree/main/services/property-svc"
        click UpdatesSvc "https://github.com/helpwave/services/tree/main/services/updates-svc"
    end

    subgraph Infrastructure
        Postgres[(PostgreSQL)]:::db
        Redis[(Redis)]:::cache
        EventStore[(EventStoreDB)]:::db
        SpiceDB["SpiceDB"]:::auth
        Jaeger["Jaeger Tracing"]:::monitoring
        
        click EventStore "https://github.com/helpwave/services/tree/main/eventstoredb"
        click SpiceDB "https://github.com/helpwave/services/tree/main/spicedb"
    end

    subgraph Definitions
        Proto["gRPC Service Definitions"]:::code
        GenCode["Generated Client Code"]:::code
        
        click Proto "https://github.com/helpwave/services/tree/main/proto/services"
        click GenCode "https://github.com/helpwave/services/tree/main/gen"
    end

    %% Client to Gateway Connections
    WebClient --> APISIX
    MobileClient --> APISIX

    %% Gateway to Service Mesh
    APISIX --> Dapr

    %% Service Mesh to Services
    Dapr --> UserSvc
    Dapr --> TasksSvc
    Dapr --> PropertySvc
    Dapr --> UpdatesSvc

    %% Services to Infrastructure
    UserSvc --> Postgres
    TasksSvc --> Postgres
    PropertySvc --> Postgres
    UpdatesSvc --> Redis
    
    UserSvc --> EventStore
    TasksSvc --> EventStore
    PropertySvc --> EventStore
    
    UserSvc --> SpiceDB
    TasksSvc --> SpiceDB
    PropertySvc --> SpiceDB

    %% Monitoring
    Dapr -.-> Jaeger
    
    %% Service Definitions
    Proto --> GenCode
    GenCode --> WebClient

    %% Styling
    classDef service fill:#3498db,stroke:#2980b9,color:white
    classDef gateway fill:#e67e22,stroke:#d35400,color:white
    classDef mesh fill:#9b59b6,stroke:#8e44ad,color:white
    classDef db fill:#2ecc71,stroke:#27ae60,color:white
    classDef cache fill:#e74c3c,stroke:#c0392b,color:white
    classDef auth fill:#f1c40f,stroke:#f39c12,color:black
    classDef monitoring fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef code fill:#34495e,stroke:#2c3e50,color:white
```
