Skip to content

ARCHITECTURE_OVERVIEW.md

Latest commit

 

History

History
346 lines (278 loc) · 12 KB

ARCHITECTURE_OVERVIEW.md

File metadata and controls

346 lines (278 loc) · 12 KB

Huly Self-Hosted Architecture Overview

Service Overview

The Huly self-hosted deployment consists of 14 services working together. This section describes each service and its role in the platform.

Application Services

Service Description
front Web application server that serves the Huly UI. Handles static assets, client-side routing, and coordinates with backend services for data and authentication.
account Authentication and user management service. Handles user registration, login, JWT token generation/validation, and workspace membership.
transactor Core transaction processing engine. Maintains WebSocket connections with clients for real-time updates, processes all data mutations, enforces business logic, and publishes events to the message queue.
workspace Workspace lifecycle management. Handles workspace creation, initialization, upgrades, and configuration. Runs background jobs for workspace maintenance.
collaborator Real-time document collaboration service using Y.js CRDT. Enables multiple users to edit documents simultaneously with automatic conflict resolution and presence awareness.
fulltext Search indexing service. Consumes events from the message queue, extracts content from documents, and maintains the Elasticsearch search index for fast full-text search.
rekoni Content intelligence service. Extracts text and structured data from binary documents (PDF, DOC, DOCX, RTF) to make them searchable. Used by fulltext service for indexing document attachments.
stats Metrics collection service. Aggregates usage statistics and health metrics from all services for monitoring and debugging.

Infrastructure Services

Service Description
nginx Reverse proxy and SSL termination. Routes external requests to internal services, handles HTTPS certificates, and provides a single entry point for all client connections.
cockroach CockroachDB - the primary database. Stores all application data including users, workspaces, documents, and metadata. Provides ACID transactions and horizontal scalability.
elastic Elasticsearch search engine. Stores and indexes document content for fast full-text search queries. Managed by the fulltext service.
minio S3-compatible object storage. Stores all binary files including attachments, images, and document blobs. Accessed directly by nginx for file downloads.
redpanda Kafka-compatible event streaming platform. Provides reliable message delivery between services for asynchronous processing (e.g., search indexing after document changes).
kvs (HulyKVS) Key-value store service. Provides fast key-value storage for application configuration, user preferences, and cached data.

Service Communication Patterns

  • Synchronous (HTTP/WebSocket): Client ↔ Nginx ↔ Services
  • Asynchronous (Events): Transactor → Redpanda → Fulltext
  • Direct Database: Services → CockroachDB
  • File Storage: Services → MinIO (via S3 API)

1. High-Level System Architecture

graph TB
    subgraph "Client Layer"
        Browser[Web Browser]
        Desktop[Desktop App]
    end
    
    subgraph "Reverse Proxy"
        Nginx[Nginx<br/>:80/:443]
    end
    
    subgraph "Frontend Layer"
        Front[Frontend Server<br/>:8080]
    end
    
    subgraph "Core Backend Services"
        Account[Account Service<br/>:3000<br/>Authentication & Users]
        Workspace[Workspace Service<br/>Workspace Management]
        Transactor[Transactor Service<br/>:3333<br/>Transaction Processing]
        Collaborator[Collaborator Service<br/>:3078<br/>Real-time Collaboration]
    end
    
    subgraph "Data Services"
        HulyKVS[HulyKVS<br/>:8094<br/>Key-Value Store]
        Fulltext[Fulltext Service<br/>:4700<br/>Search Indexing]
        Rekoni[Rekoni Service<br/>:4004<br/>AI/ML Recognition]
    end
    
    subgraph "Monitoring"
        Stats[Stats Service<br/>:4900<br/>Metrics Collection]
    end
    
    subgraph "Primary Database"
        CockroachDB[(CockroachDB<br/>:26257<br/>Distributed SQL)]
    end
    
    subgraph "Supporting Infrastructure"
        Elasticsearch[(Elasticsearch<br/>:9200<br/>Search Engine)]
        Minio[(MinIO<br/>:9000<br/>Object Storage)]
        Redpanda[Redpanda<br/>:9092<br/>Event Streaming]
    end
    
    Browser --> Nginx
    Desktop --> Nginx
    Nginx --> Front
    Nginx --> Account
    Nginx --> Transactor
    Nginx --> Collaborator
    
    Account --> CockroachDB
    Workspace --> CockroachDB
    Transactor --> CockroachDB
    Transactor --> Fulltext
    Transactor --> Redpanda
    
    HulyKVS --> CockroachDB
    
    Fulltext --> Elasticsearch
    Fulltext --> CockroachDB
    Fulltext --> Rekoni
    Fulltext --> Redpanda
    
    Workspace --> Redpanda
    Account --> Redpanda
    
    Collaborator --> Minio
    Front --> Minio
    
    style Front fill:#4A90E2
    style Account fill:#E24A4A
    style Transactor fill:#E24A4A
    style CockroachDB fill:#7ED321
    style Redpanda fill:#F5A623
    style Nginx fill:#009639
Loading

2. Network Topology & Nginx Routing

graph TB
    subgraph "External Access"
        Client[Client Browser/Desktop]
    end
    
    subgraph "Reverse Proxy - Nginx :80/:443"
        Nginx[Nginx]
        
        subgraph "Route Mappings"
            R1["/ → front:8080"]
            R2["/_accounts → account:3000"]
            R3["/_transactor → transactor:3333"]
            R4["/_collaborator → collaborator:3078"]
            R5["/_rekoni → rekoni:4004"]
            R6["/_stats → stats:4900"]
            R7["/files → minio:9000"]
        end
    end
    
    subgraph "Application Services"
        Front[Front :8080]
        Account[Account :3000]
        Transactor[Transactor :3333]
        Collaborator[Collaborator :3078]
        Rekoni[Rekoni :4004]
        Stats[Stats :4900]
        Workspace[Workspace]
        Fulltext[Fulltext :4700]
        HulyKVS[HulyKVS :8094]
    end
    
    subgraph "Primary Database"
        CockroachDB[(CockroachDB :26257)]
    end
    
    subgraph "Supporting Infrastructure"
        Elasticsearch[(Elasticsearch :9200)]
        Minio[(MinIO :9000/:9001)]
        Redpanda[Redpanda :9092/:19092]
    end
    
    Client --> Nginx
    
    Nginx --> R1 --> Front
    Nginx --> R2 --> Account
    Nginx --> R3 --> Transactor
    Nginx --> R4 --> Collaborator
    Nginx --> R5 --> Rekoni
    Nginx --> R6 --> Stats
    Nginx --> R7 --> Minio
    
    style Nginx fill:#009639
    style Front fill:#4A90E2
    style Transactor fill:#E24A4A
    style CockroachDB fill:#7ED321
    style Redpanda fill:#F5A623
Loading

3. Event-Driven Architecture (Redpanda/Kafka)

graph LR
    subgraph "Event Producers"
        Transactor[Transactor<br/>Transaction Events]
        Workspace[Workspace<br/>Workspace Events]
        Account[Account<br/>Account Events]
    end
    
    subgraph "Event Bus"
        Redpanda[Redpanda<br/>Kafka Topics<br/>:9092]
    end
    
    subgraph "Event Consumers"
        Fulltext[Fulltext<br/>Indexing]
    end
    
    subgraph "Queue Configuration"
        QC[QUEUE_CONFIG<br/>redpanda:9092]
    end
    
    Transactor -->|Document Events| Redpanda
    Transactor -->|User Actions| Redpanda
    Workspace -->|Workspace Events| Redpanda
    Account -->|Account Events| Redpanda
    
    Redpanda -->|Index Events| Fulltext
    
    QC -.Config.-> Transactor
    QC -.Config.-> Workspace
    QC -.Config.-> Fulltext
    QC -.Config.-> Account
    
    style Redpanda fill:#F5A623
    style Transactor fill:#E24A4A
Loading

4. Authentication & Authorization Flow

sequenceDiagram
    participant Client
    participant Nginx
    participant Front
    participant Account
    participant Transactor
    participant Workspace
    participant CockroachDB
    
    Client->>Nginx: Login Request
    Nginx->>Front: Proxy
    Front->>Account: Authenticate
    Account->>CockroachDB: Verify Credentials
    CockroachDB-->>Account: User Record
    Account->>Account: Generate Token<br/>(SERVER_SECRET)
    Account-->>Front: JWT Token
    Front-->>Client: Token + Workspace List
    
    Client->>Nginx: Connect to Workspace
    Nginx->>Account: Verify Token (/_accounts)
    Account-->>Nginx: Token Valid + User Info
    
    Nginx->>Workspace: Get Workspace Info
    Workspace->>CockroachDB: Query Workspace
    CockroachDB-->>Workspace: Workspace Data
    Workspace-->>Nginx: Workspace Config
    
    Client->>Nginx: WebSocket Connect
    Nginx->>Transactor: Proxy to /_transactor
    Transactor->>Account: Verify Token
    Account-->>Transactor: User Authorized
    Transactor->>CockroachDB: Load User Permissions
    Transactor-->>Client: Connected
    
    Note over Client,CockroachDB: All services share SERVER_SECRET<br/>for internal authentication
Loading

Service Summary Table

Service Container Port Purpose Dependencies
Reverse Proxy
nginx nginx:1.21.3 80/443 Reverse proxy, SSL termination all services
Frontend
front hardcoreeng/front 8080 Web application server account, minio
Core
account hardcoreeng/account 3000 Authentication & user management cockroach, redpanda
transactor hardcoreeng/transactor 3333 Transaction processing (WebSocket) cockroach, redpanda, fulltext
workspace hardcoreeng/workspace - Workspace management cockroach, redpanda, minio
collaborator hardcoreeng/collaborator 3078 Real-time document collaboration account, minio
Storage
kvs (HulyKVS) hardcoreeng/hulykvs 8094 Key-value store cockroach
Search
fulltext hardcoreeng/fulltext 4700 Full-text search indexing elasticsearch, cockroach, rekoni, redpanda
rekoni hardcoreeng/rekoni-service 4004 AI/ML recognition service -
Monitoring
stats hardcoreeng/stats 4900 Metrics collection -
Primary Database
cockroach cockroachdb/cockroach 26257 Distributed SQL database -
Supporting Infrastructure
elastic elasticsearch:7.14.2 9200 Search engine -
minio minio/minio 9000/9001 Object storage -
redpanda redpandadata/redpanda 9092/19092 Event streaming (Kafka) -

Environment Variables Summary

Common Configuration

  • SECRET / SERVER_SECRET: Shared authentication secret
  • STORAGE_CONFIG: minio|minio?accessKey=minioadmin&secretKey=minioadmin
  • QUEUE_CONFIG: redpanda:9092

Database Configuration

  • DB_URL: CockroachDB connection string (e.g., postgresql://user:pass@cockroach:26257/huly)
  • FULLTEXT_DB_URL: http://elastic:9200

Service URLs (Internal)

  • ACCOUNTS_URL: http://account:3000
  • TRANSACTOR_URL: ws://transactor:3333
  • FULLTEXT_URL: http://fulltext:4700
  • REKONI_URL: http://rekoni:4004
  • STATS_URL: http://stats:4900

External URLs (via Nginx)

  • Frontend: http(s)://${HOST_ADDRESS}/
  • Accounts API: http(s)://${HOST_ADDRESS}/_accounts
  • Transactor WebSocket: ws(s)://${HOST_ADDRESS}/_transactor
  • Collaborator WebSocket: ws(s)://${HOST_ADDRESS}/_collaborator
  • Files: http(s)://${HOST_ADDRESS}/files
  • Rekoni: http(s)://${HOST_ADDRESS}/_rekoni
  • Stats: http(s)://${HOST_ADDRESS}/_stats

Services NOT Included in Self-Hosted

The following services are available in Huly Cloud/Enterprise but not included in the self-hosted deployment:

Service Purpose
Datalake Advanced blob storage management
Hulylake Storage adapter API
HulyPulse WebSocket push notifications
HulyGun Event processing
Redis Cache & pub/sub
Rating Content rating service
Print PDF generation
Sign Digital signatures
Payment Billing integration
Export Data export
Analytics Analytics collection
Process Workflow automation
Stream Video streaming
Media Media processing
Preview Thumbnail generation
Backup/Backup-API Backup services
Jaeger Distributed tracing