# datum-cloud/cloud-portal architecture

> Architecture diagram of the GitHub repository datum-cloud/cloud-portal, 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/datum-cloud/cloud-portal
- Repository: https://github.com/datum-cloud/cloud-portal

## Overview

##### Project Type & Purpose
- Full-stack Remix web portal (“Datum Cloud Portal”) for managing cloud resources via a control-plane API.
- Provides UI for projects, networks, workloads, secrets, export-policies, etc., backed by a code-generated SDK and REST/GraphQL layers.

##### Main Components
- Frontend (React/TypeScript, Remix, shadcn/ui, Tailwind CSS)
- Feature modules under app/features (e.g., workload, network, observe)
- Shared components under app/components
- State management: Jotai (local) & TanStack Query (server‐state)
- Routing: Remix routes in app/routes & API routes in app/routes/api+
- Backend (Remix server in server.ts & entry.server.ts)
- Loaders/actions for data fetching & form handling
- Middleware for auth & CSRF in app/modules/middleware
- i18n, unstorage, and auth modules
- API Layer
- Control-plane SDK (code-gen under app/modules/control-plane)
- Axios module for HTTP transport
- Resources/controllers in app/resources mapping UI calls to SDK
- GraphQL client under app/modules/graphql (optional)
- External Services
- Cloud control-plane (compute, network, telemetry, resource-manager)
- Monitoring (Prometheus, Grafana via Docker/dev manifests)
- CI/CD (GitHub Actions) & Observability (Sentry, Fathom)

##### Component Relationships & Data Flow
- Browser → Remix Server: request page or submit form
- Remix Server Loader/Action → Resources → Control-Plane SDK (via Axios) → Cloud API
- Response → Remix Server → Serialized JSON → Browser
- Frontend fetches/caches with TanStack Query; global state via Jotai

##### Architectural Patterns
- Feature-based modularization: each domain in its own folder
- Layered API adapter: UI → resources/controllers → SDK → HTTP → Cloud API
- Server/client separation via Remix loaders/actions and React components
- Code generation for API schemas and SDK ensures type safety

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        ReactUI["React UI Components"]:::frontend
        Features["Feature Modules"]:::frontend
        StateHooks["State Management Hooks"]:::frontend
        Providers["Providers (Context & Global State)"]:::frontend
        EntryClient["Remix Client Entry Point"]:::frontend
    end

    %% Server Layer
    subgraph "Remix Server" 
        direction TB
        EntryServer["Remix Server Entry Point"]:::server
        RoutesUI["UI Routes"]:::server
        RoutesAPI["API Routes"]:::server
        AuthModule["Auth Module"]:::server
        Middleware["Middleware (Auth/CSRF)"]:::server
        I18n["Internationalization"]:::server
        Unstorage["Unstorage"]:::server
        Utils["Utilities"]:::server
    end

    %% API Adapter Layer
    subgraph "API Adapter" 
        direction TB
        Axios["HTTP Transport (Axios)"]:::api
        ControlPlaneSDK["Control-Plane SDK"]:::api
        Resources["Resource Controllers"]:::api
        GraphQLClient["GraphQL Client"]:::api
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Cloud["Cloud Control-Plane"]:::external
        Monitoring["Monitoring (Prometheus, Grafana)"]:::external
        CICD["CI/CD & Observability"]:::external
    end

    %% Flows
    ReactUI -->|"HTTP Request / Navigation"| EntryServer
    EntryServer -->|Loader/Action Calls| Resources
    Resources -->|SDK Calls| ControlPlaneSDK
    ControlPlaneSDK -->|HTTP API| Cloud
    EntryServer -->|"Serialized JSON"| ReactUI
    ReactUI -->|TanStack Query| RoutesAPI
    EntryServer -->|"Runs Routes"| RoutesUI
    EntryServer -->|Middleware| AuthModule
    AuthModule -->|Session| Middleware
    EntryServer -->|i18n| I18n

    %% Click Events
    click ReactUI "https://github.com/datum-cloud/cloud-portal/tree/main/app/components"
    click Features "https://github.com/datum-cloud/cloud-portal/tree/main/app/features"
    click StateHooks "https://github.com/datum-cloud/cloud-portal/tree/main/app/hooks"
    click Providers "https://github.com/datum-cloud/cloud-portal/tree/main/app/providers"
    click EntryClient "https://github.com/datum-cloud/cloud-portal/blob/main/app/entry.client.tsx"
    click EntryServer "https://github.com/datum-cloud/cloud-portal/blob/main/app/entry.server.tsx"
    click EntryServer "https://github.com/datum-cloud/cloud-portal/blob/main/server.ts"
    click RoutesUI "https://github.com/datum-cloud/cloud-portal/tree/main/app/routes"
    click RoutesAPI "https://github.com/datum-cloud/cloud-portal/tree/main/app/routes/api+"
    click AuthModule "https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/auth/auth.server.ts"
    click Middleware "https://github.com/datum-cloud/cloud-portal/tree/main/app/modules/middleware"
    click I18n "https://github.com/datum-cloud/cloud-portal/tree/main/app/modules/i18n"
    click Unstorage "https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/unstorage/unstorage.ts"
    click Utils "https://github.com/datum-cloud/cloud-portal/tree/main/app/utils"
    click Axios "https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/axios/axios.ts"
    click ControlPlaneSDK "https://github.com/datum-cloud/cloud-portal/tree/main/app/modules/control-plane"
    click Resources "https://github.com/datum-cloud/cloud-portal/tree/main/app/resources"
    click GraphQLClient "https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/graphql/graphql.ts"
    click Providers "https://github.com/datum-cloud/cloud-portal/tree/main/app/constants"
    click Monitoring "https://github.com/datum-cloud/cloud-portal/tree/main/dev/docker"
    click CICD "https://github.com/datum-cloud/cloud-portal/tree/main/config"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef server fill:#E0FFE0,stroke:#28A745,color:#28A745;
    classDef api fill:#FFF4D0,stroke:#E67700,color:#E67700;
    classDef external fill:#FFE0E0,stroke:#D73A49,color:#D73A49;
```
