# tritondatacenter/sdc-ufds architecture

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

- Interactive diagram: https://gitdiagram.com/tritondatacenter/sdc-ufds
- Repository: https://github.com/tritondatacenter/sdc-ufds

## Overview

##### Project type and purpose
- This is a backend, middleware‐type microservice within the Triton Data Center: “SDC-UFDS” (Unified Foundational Directory Service).
- It exposes both an LDAP API (via ldapjs) and an HTTP “CAPI” shim for backwards compatibility, stores metadata in Moray (a Triton data store), and includes a replicator service to sync data across data centers.

##### File-structure analysis
- Top level:
- main.js, capi.js, replicator.js – entry points for the core UFDS server, the CAPI shim, and the cross-DC replicator.
- bin/ – CLI scripts for installation, filtering, reconciliation, etc.
- etc/config*.json & smf/manifests & sapi_manifests/ – deployment and service-management manifests (SmartOS SMF, Scalr API manifest templates).
- data/ – LDIF and SQL scripts for bootstrapping and schema updates.
- schema/ – UFDS schema definitions (custom Validator subclasses).
- lib/ – core business logic split into:
– lib/db/ (Moray client wrappers: add, search, modify, delete)
– lib/schema/ (schema loader/validator)
– lib/ufds-replicator/ (replicator engine)
– lib/ufds.js (core server orchestration)
- capi/ – modules implementing the HTTP CAPI endpoints: login, customers, keys, limits, metadata, fraud, etc.
- deps/haproxy/ – vendored HAProxy source (used to build a custom load-balancer).
- test/ – unit/integration tests for DB, schema, CAPI, replicator.

##### README insights
- UFDS sits on ldapjs + Moray.
- CAPI shim mimics the older SDC 6.5 HTTP API.
- Dynamic schema discovery: at startup UFDS auto-loads all files under ./schema.
- Development requires a running Moray instance as configured in etc/config*.json.

##### Be detailed
- Major modules: capi/*, lib/db, lib/ufds-replicator, schema/.
- Both synchronous flows (client → UFDS → Moray) and asynchronous ones (replicator → remote Moray).
- Where configuration (etc/config.json) and bootstrap data (data/*.ldif) fit in during startup.
- Don’t omit the HAProxy layer or the SMF/service-manifest artifacts as they’re critical to how UFDS is deployed and scaled.
- The end result should clearly map directories/modules → runtime components → external dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "External Clients"
    LDAPClients["Operators/Services (LDAP 389/636)"]:::client
    HTTPClients["HTTP Clients (CAPI 8081-8084)"]:::client
  end

  LDAPClients --> HAProxy
  HTTPClients --> HAProxy

  HAProxy["HAProxy Load-Balancer"]:::deployment
  click HAProxy "https://github.com/tritondatacenter/sdc-ufds/blob/master/etc/haproxy.cfg.in"
  HAProxy --> LDAPLayer
  HAProxy --> HTTPLayer

  subgraph "UFDS Cluster"
    subgraph "App Instance"
      LDAPLayer["LDAP Layer (ldapjs)"]:::core
      HTTPLayer["HTTP CAPI Shim"]:::core
      click HTTPLayer "https://github.com/tritondatacenter/sdc-ufds/tree/master/capi/"
      SchemaLoader["Schema Loader & Validator"]:::core
      click SchemaLoader "https://github.com/tritondatacenter/sdc-ufds/tree/master/schema/"
      DBLayer["Moray Access Layer"]:::core
      click DBLayer "https://github.com/tritondatacenter/sdc-ufds/tree/master/lib/db/"
      Orchestrator["Core Server Orchestration"]:::core
      click Orchestrator "https://github.com/tritondatacenter/sdc-ufds/blob/master/lib/ufds.js"
    end
  end

  LDAPLayer --> Orchestrator
  HTTPLayer --> Orchestrator
  Orchestrator --> SchemaLoader
  SchemaLoader --> DBLayer
  DBLayer --> MorayDB

  subgraph "Storage"
    MorayDB["Moray Document Store"]:::storage
    RemoteMoray["Remote Moray Clusters"]:::storage
  end

  DBLayer -.->|"on write"| ReplicatorEngine
  ReplicatorEngine --> RemoteMoray

  subgraph "Replication Layer"
    ReplicatorService["Replicator Service"]:::core
    click ReplicatorService "https://github.com/tritondatacenter/sdc-ufds/blob/master/replicator.js"
    ReplicatorService --> ReplicatorEngine
    ReplicatorEngine["Replicator Engine"]:::core
    click ReplicatorEngine "https://github.com/tritondatacenter/sdc-ufds/tree/master/lib/ufds-replicator/"
  end

  subgraph "Operational Artifacts"
    MainEP["main.js"]:::deployment
    click MainEP "https://github.com/tritondatacenter/sdc-ufds/blob/master/main.js"
    CAPIEntry["capi.js"]:::deployment
    click CAPIEntry "https://github.com/tritondatacenter/sdc-ufds/blob/master/capi.js"
    CLI["CLI Scripts (bin/)"]:::deployment
    click CLI "https://github.com/tritondatacenter/sdc-ufds/tree/master/bin/"
    Bootstrap["Bootstrap Loader (LDIF/SQL)"]:::deployment
    click Bootstrap "https://github.com/tritondatacenter/sdc-ufds/tree/master/data/"
    HAProxySrc["HAProxy Source"]:::deployment
    click HAProxySrc "https://github.com/tritondatacenter/sdc-ufds/tree/master/deps/haproxy/"
    Config["Config Files"]:::deployment
    click Config "https://github.com/tritondatacenter/sdc-ufds/blob/master/etc/config.coal.json"
    Manifests["SMF & API Manifests"]:::deployment
    click Manifests "https://github.com/tritondatacenter/sdc-ufds/tree/master/smf/manifests/"
  end

  Config --> Orchestrator
  Config --> HAProxy
  Bootstrap --> MorayDB
  CLI --> Orchestrator
  HAProxySrc --> HAProxy
  Manifests --> Orchestrator

  classDef client fill:#cce5ff,stroke:#333,stroke-width:1px;
  classDef core fill:#d4edda,stroke:#333,stroke-width:1px;
  classDef storage fill:#ffe5b4,stroke:#333,stroke-width:1px;
  classDef deployment fill:#e2d6f2,stroke:#333,stroke-width:1px;
```
