# opencloud-eu/opencloud architecture

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

- Interactive diagram: https://gitdiagram.com/opencloud-eu/opencloud
- Repository: https://github.com/opencloud-eu/opencloud

## Overview

##### System’s main logical layers and components
- **Clients**: Browsers (UI), CLI (`opencloud` binary), acceptance‐test harness
- **Ingress / API Gateway**: `services/gateway` (HTTP + gRPC routing & proxy)
- **Authentication/Identity**:
- External IdP (Keycloak) or
- Embedded LibreGraph Connect (`services/idp`, generated via Hugo & React UI under `services/idp/src`)
- **Microservices Layer**: dozens of Go services under `services/…` (e.g. `sharing`, `search`, `settings`, `collaboration`, `ocs`, `notifications`, `activitylog`, `app‐registry`, etc.)
- **Messaging/Event‐Bus**: NATS (`services/nats`) for pub/sub between services
- **Shared Libraries & Utilities**: the `pkg/…` modules (config, middleware, logging, OIDC, registry, crypto, conversions, clihelper, protogen generated code under `protogen/…`)
- **Runtime Orchestrator & CLI**: the `opencloud` binary under `opencloud/cmd/opencloud` and its runtime package (`opencloud/pkg/runtime`) which can spawn and supervise services locally
- **Data Store**: local filesystem (rooted at `$HOME/.opencloud`) – no traditional database

##### Component relationships & data flows
- **Client → Gateway** (HTTP/REST & gRPC)
- **Gateway → Microservices** (routes requests by URL or gRPC service namespace)
- **Microservices ↔ NATS** (publish/subscribe events)
- **Microservices ↔ Filesystem** (read/write application data, logs)
- **Microservices ↔ Identity Provider** (OIDC token validation via HTTP/gRPC)
- **Microservices ↔ Shared Libraries** (internal call Graph of `pkg/…` modules and `protogen`‐generated stubs)
- **Runtime → Services** (invokes each service binary or goroutine via the runtime package)

##### Core architectural patterns & principles
- **Microservices**: each service in `services/…` is an independent Go module, built into its own binary.
- **API Gateway**: central entry point that enforces cross‐cutting concerns (auth, logging, rate‐limit) before routing.
- **Event-Driven**: NATS for loosely coupled asynchronous communication.
- **Shared Code Modules**: common concerns (config, logging, middleware) live in `pkg/…` and are imported by all services.
- **Code Generation**: proto definitions under `protogen/proto` → code under `protogen/gen` produce consistent gRPC + HTTP bindings.
- **Filesystem as Storage**: domain data (settings, users, shares, notifications) is serialized to disk – highlight that no RDBMS is used.

##### Detail level
- Major service group rather than all 70+ services individually; illustrate examples (Sharing, OCS, Collaboration, Search).
- How the OpenCloud CLI (`opencloud server`) uses the `opencloud/pkg/runtime` to start/monitor services locally for development.
- That acceptance tests spin up infrastructure via Docker Compose configs in `deployments/examples/opencloud_full`.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Clients Layer
  subgraph "Clients"
    Browser["Web UI"]:::frontend
    CLI["CLI (`opencloud` binary)"]:::cli
    Tests["Acceptance Tests"]:::tests
  end

  %% API Gateway & Authentication
  subgraph "API Gateway & Authentication"
    Gateway["services/gateway"]:::transport
    Keycloak["Keycloak (External IdP)"]:::external
    Idp["services/idp"]:::auth
  end

  %% Microservices Layer
  subgraph "Microservices"
    Sharing["services/sharing"]:::domain
    Search["services/search"]:::domain
    Settings["services/settings"]:::domain
    Collaboration["services/collaboration"]:::domain
    OCS["services/ocs"]:::domain
    Notifications["services/notifications"]:::domain
    ActivityLog["services/activitylog"]:::domain
    AppRegistry["services/app-registry"]:::domain
  end

  %% Side Components
  NATS["NATS (services/nats)"]:::infra
  Shared["Shared Libraries & Code Generation\n(pkg/ & protogen/)"]:::shared

  %% Runtime & Helpers
  subgraph "OpenCloud CLI & Runtime"
    Runtime["opencloud/pkg/runtime"]:::runtime
    Command["opencloud/pkg/command"]:::shared
    Backup["opencloud/pkg/backup"]:::shared
    Init["opencloud/pkg/init"]:::shared
  end

  %% Data Store
  FS["Filesystem Storage\n($HOME/.opencloud)"]:::infra

  %% Relationships
  Browser -->|"HTTP/gRPC"| Gateway
  CLI -->|uses runtime| Runtime
  Tests -->|"HTTP/gRPC"| Gateway

  Gateway -->|"routes"| Sharing
  Gateway -->|"routes"| Search
  Gateway -->|"routes"| Settings
  Gateway -->|"routes"| Collaboration
  Gateway -->|"routes"| OCS
  Gateway -->|"routes"| Notifications
  Gateway -->|"routes"| ActivityLog
  Gateway -->|"routes"| AppRegistry

  Sharing ---|pub/sub| NATS
  Search ---|pub/sub| NATS
  Settings ---|pub/sub| NATS
  Collaboration ---|pub/sub| NATS
  OCS ---|pub/sub| NATS
  Notifications ---|pub/sub| NATS
  ActivityLog ---|pub/sub| NATS
  AppRegistry ---|pub/sub| NATS

  Sharing -->|"read/write"| FS
  Search -->|"read/write"| FS
  Settings -->|"read/write"| FS
  Collaboration -->|"read/write"| FS
  OCS -->|"read/write"| FS
  Notifications -->|"read/write"| FS
  ActivityLog -->|"read/write"| FS
  AppRegistry -->|"read/write"| FS

  Sharing -->|"auth via OIDC"| Idp
  Search -->|"auth via OIDC"| Idp
  Settings -->|"auth via OIDC"| Idp
  Collaboration -->|"auth via OIDC"| Idp
  OCS -->|"auth via OIDC"| Idp
  Notifications -->|"auth via OIDC"| Idp
  ActivityLog -->|"auth via OIDC"| Idp
  AppRegistry -->|"auth via OIDC"| Idp

  Sharing -->|"imports"| Shared
  Search -->|"imports"| Shared
  Settings -->|"imports"| Shared
  Collaboration -->|"imports"| Shared
  OCS -->|"imports"| Shared
  Notifications -->|"imports"| Shared
  ActivityLog -->|"imports"| Shared
  AppRegistry -->|"imports"| Shared

  Runtime -->|spawns| Sharing
  Runtime -->|spawns| Search
  Runtime -->|spawns| Settings
  Runtime -->|spawns| Collaboration
  Runtime -->|spawns| OCS
  Runtime -->|spawns| Notifications
  Runtime -->|spawns| ActivityLog
  Runtime -->|spawns| AppRegistry

  %% Click Events
  click Browser "https://github.com/opencloud-eu/opencloud/tree/main/services/web"
  click CLI "https://github.com/opencloud-eu/opencloud/blob/main/opencloud/cmd/opencloud/main.go"
  click Tests "https://github.com/opencloud-eu/opencloud/tree/main/tests/acceptance"
  click Gateway "https://github.com/opencloud-eu/opencloud/tree/main/services/gateway"
  click Idp "https://github.com/opencloud-eu/opencloud/tree/main/services/idp"
  click Sharing "https://github.com/opencloud-eu/opencloud/tree/main/services/sharing"
  click Search "https://github.com/opencloud-eu/opencloud/tree/main/services/search"
  click Settings "https://github.com/opencloud-eu/opencloud/tree/main/services/settings"
  click Collaboration "https://github.com/opencloud-eu/opencloud/tree/main/services/collaboration"
  click OCS "https://github.com/opencloud-eu/opencloud/tree/main/services/ocs"
  click Notifications "https://github.com/opencloud-eu/opencloud/tree/main/services/notifications"
  click ActivityLog "https://github.com/opencloud-eu/opencloud/tree/main/services/activitylog"
  click AppRegistry "https://github.com/opencloud-eu/opencloud/tree/main/services/app-registry"
  click NATS "https://github.com/opencloud-eu/opencloud/tree/main/services/nats"
  click Shared "https://github.com/opencloud-eu/opencloud/tree/main/pkg/"
  click Shared "https://github.com/opencloud-eu/opencloud/tree/main/protogen/"
  click Runtime "https://github.com/opencloud-eu/opencloud/tree/main/opencloud/pkg/runtime"
  click Command "https://github.com/opencloud-eu/opencloud/tree/main/opencloud/pkg/command"
  click Backup "https://github.com/opencloud-eu/opencloud/tree/main/opencloud/pkg/backup"
  click Init "https://github.com/opencloud-eu/opencloud/tree/main/opencloud/pkg/init"

  %% Styles
  classDef transport fill:#cce5ff,stroke:#004085,color:#004085;
  classDef domain fill:#d4edda,stroke:#155724,color:#155724;
  classDef infra fill:#fff3cd,stroke:#856404,color:#856404;
  classDef shared fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
  classDef auth fill:#f8d7da,stroke:#721c24,color:#721c24;
  classDef external fill:#f5c6cb,stroke:#721c24,color:#721c24;
  classDef cli fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
  classDef tests fill:#d6d8db,stroke:#1b1e21,color:#1b1e21;
  classDef runtime fill:#f0e5ff,stroke:#4b0082,color:#4b0082;
```
