# d1abloo/instancias-briefly architecture

> Architecture diagram of the GitHub repository d1abloo/instancias-briefly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/d1abloo/instancias-briefly
- Repository: https://github.com/d1abloo/instancias-briefly

## Overview

Briefly is a control plane for ephemeral Linux instances: users launch work from the panel, the scheduler selects a node, and the instance manager provisions an isolated container; expiry removes its resources and terminal credentials. The repository also exposes cloud environments, stacks, databases, deployments, account/security, and administration capabilities. The principal workflow is documented in the README; several worker interactions and subsystem links are inferred only at the documented level because their wiring was not excerpted.

Main entry points: [`services/scheduler/src/main.ts`](https://github.com/d1abloo/instancias-briefly/blob/main/services/scheduler/src/main.ts) (Node scheduler), [`apps/api/src/instances/instances.service.ts`](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/instances/instances.service.ts) (Instance lifecycle API), [`services/instance-manager/src/main.ts`](https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/main.ts) (Instance manager), [`apps/api/src/instances/cloud-adapter.ts`](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/instances/cloud-adapter.ts) (Cloud environments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_panel["User panel"]
  node_web["Web panel<br/>[index.tsx]"]
end

subgraph group_control["API control plane"]
  node_api["Application API<br/>[app.module.ts]"]
  node_instance_api["Instance lifecycle API"]
  node_cloud_api["Cloud environments<br/>[cloud-adapter.ts]"]
  node_deployments["Deployments"]
  node_stacks["Stacks<br/>[stacks.service.ts]"]
  node_databases["Managed databases"]
  node_capacity["Capacity policy<br/>[capacity.ts]"]
  node_platform["Account and platform"]
  node_admin["Administration<br/>[admin.service.ts]"]
end

subgraph group_workers["Job workers"]
  node_scheduler["Node scheduler<br/>[main.ts]"]
  node_deployment_worker["Deployment worker<br/>[index.ts]"]
  node_stack_orchestrator["Stack orchestrator<br/>[index.ts]"]
  node_reconciler["Resource reconciler<br/>[main.ts]"]
  node_resource_reconciler["Resource reconciliation<br/>[index.ts]"]
  node_metrics["Metrics collection<br/>[main.ts]"]
  node_queue["Job queue"]
end

subgraph group_runtime["Node runtime"]
  node_instance_manager["Instance manager<br/>[main.ts]"]
  node_host["Container provisioning<br/>[host.ts]"]
  node_floci["Local cloud services<br/>[floci.ts]"]
end

subgraph group_operations["Operations and access"]
  node_terminal["Terminal gateway<br/>[main.ts]"]
  node_access["Resource access<br/>[access.ts]"]
  node_config_apps["App catalog policy<br/>[apps.ts]"]
  node_database[("Persistent state")]
end

node_user(("User"))
node_node["Linux node"]

node_user -->|"uses"| node_web
node_web -.->|"requests"| node_api
node_api -.->|"routes lifecycle"| node_instance_api
node_instance_api -.->|"enqueues work"| node_scheduler
node_scheduler -->|"adds jobs"| node_queue
node_scheduler -->|"selects and updates"| node_database
node_scheduler -.->|"dispatches jobs"| node_instance_manager
node_instance_manager -->|"provisions"| node_host
node_host -->|"runs isolated containers"| node_node
node_instance_manager -->|"records job state"| node_database
node_cloud_api -->|"loads cloud runtime"| node_instance_api
node_cloud_api -.->|"proxies cloud requests"| node_floci
node_deployments -.->|"dispatches deployments"| node_deployment_worker
node_stacks -.->|"orchestrates stacks"| node_stack_orchestrator
node_databases -->|"checks capacity"| node_capacity
node_stacks -->|"checks capacity"| node_capacity
node_instance_api -.->|"validates app manifests"| node_config_apps
node_reconciler -->|"sweeps resource state"| node_database
node_resource_reconciler -.->|"reconciles resources"| node_database
node_metrics -->|"stores metrics and logs"| node_database
node_terminal -->|"validates terminal claim"| node_database
node_terminal -->|"attaches terminal"| node_node
node_access -.->|"manages access state"| node_database
node_platform -.->|"manages account resources"| node_database
node_admin -.->|"reads operations state"| node_database

click node_web "https://github.com/d1abloo/instancias-briefly/blob/main/apps/web/src/pages/instances/index.tsx"
click node_api "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/app.module.ts"
click node_instance_api "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/instances/instances.service.ts"
click node_cloud_api "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/instances/cloud-adapter.ts"
click node_deployments "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/modules/deployments/deployments.service.ts"
click node_stacks "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/modules/stacks/stacks.service.ts"
click node_databases "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/modules/databases/databases.service.ts"
click node_capacity "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/modules/capacity.ts"
click node_platform "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/platform/platform.service.ts"
click node_admin "https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/admin/admin.service.ts"
click node_scheduler "https://github.com/d1abloo/instancias-briefly/blob/main/services/scheduler/src/main.ts"
click node_deployment_worker "https://github.com/d1abloo/instancias-briefly/blob/main/services/deployment-worker/src/index.ts"
click node_stack_orchestrator "https://github.com/d1abloo/instancias-briefly/blob/main/services/stack-orchestrator/src/index.ts"
click node_reconciler "https://github.com/d1abloo/instancias-briefly/blob/main/services/reconciler/src/main.ts"
click node_resource_reconciler "https://github.com/d1abloo/instancias-briefly/blob/main/services/resource-reconciler/src/index.ts"
click node_metrics "https://github.com/d1abloo/instancias-briefly/blob/main/services/metrics-worker/src/main.ts"
click node_instance_manager "https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/main.ts"
click node_host "https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/host.ts"
click node_floci "https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/floci.ts"
click node_terminal "https://github.com/d1abloo/instancias-briefly/blob/main/services/terminal-gateway/src/main.ts"
click node_access "https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/access.ts"
click node_config_apps "https://github.com/d1abloo/instancias-briefly/blob/main/packages/config/src/apps.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_user toneBlue
class node_api,node_instance_api,node_cloud_api,node_deployments,node_stacks,node_databases,node_capacity,node_platform,node_admin toneAmber
class node_scheduler,node_deployment_worker,node_stack_orchestrator,node_reconciler,node_resource_reconciler,node_metrics,node_queue toneMint
class node_instance_manager,node_host,node_floci toneRose
class node_terminal,node_access,node_config_apps,node_database,node_node toneIndigo
```

## Components

### User panel

- [Web panel](https://github.com/d1abloo/instancias-briefly/blob/main/apps/web/src/pages/instances/index.tsx): `apps/web/src/pages/instances/index.tsx`

### API control plane

- [Application API](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`
- [Instance lifecycle API](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/instances/instances.service.ts): `apps/api/src/instances/instances.service.ts`
- [Cloud environments](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/instances/cloud-adapter.ts): `apps/api/src/instances/cloud-adapter.ts`
- [Deployments](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/modules/deployments/deployments.service.ts): `apps/api/src/modules/deployments/deployments.service.ts`
- [Stacks](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/modules/stacks/stacks.service.ts): `apps/api/src/modules/stacks/stacks.service.ts`
- [Managed databases](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/modules/databases/databases.service.ts): `apps/api/src/modules/databases/databases.service.ts`
- [Capacity policy](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/modules/capacity.ts): `apps/api/src/modules/capacity.ts`
- [Account and platform](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/platform/platform.service.ts): `apps/api/src/platform/platform.service.ts`
- [Administration](https://github.com/d1abloo/instancias-briefly/blob/main/apps/api/src/admin/admin.service.ts): `apps/api/src/admin/admin.service.ts`

### Job workers

- [Node scheduler](https://github.com/d1abloo/instancias-briefly/blob/main/services/scheduler/src/main.ts): `services/scheduler/src/main.ts`
- [Deployment worker](https://github.com/d1abloo/instancias-briefly/blob/main/services/deployment-worker/src/index.ts): `services/deployment-worker/src/index.ts`
- [Stack orchestrator](https://github.com/d1abloo/instancias-briefly/blob/main/services/stack-orchestrator/src/index.ts): `services/stack-orchestrator/src/index.ts`
- [Resource reconciler](https://github.com/d1abloo/instancias-briefly/blob/main/services/reconciler/src/main.ts): `services/reconciler/src/main.ts`
- [Resource reconciliation](https://github.com/d1abloo/instancias-briefly/blob/main/services/resource-reconciler/src/index.ts): `services/resource-reconciler/src/index.ts`
- [Metrics collection](https://github.com/d1abloo/instancias-briefly/blob/main/services/metrics-worker/src/main.ts): `services/metrics-worker/src/main.ts`
- **Job queue**

### Node runtime

- [Instance manager](https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/main.ts): `services/instance-manager/src/main.ts`
- [Container provisioning](https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/host.ts): `services/instance-manager/src/host.ts`
- [Local cloud services](https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/floci.ts): `services/instance-manager/src/floci.ts`

### Operations and access

- [Terminal gateway](https://github.com/d1abloo/instancias-briefly/blob/main/services/terminal-gateway/src/main.ts): `services/terminal-gateway/src/main.ts`
- [Resource access](https://github.com/d1abloo/instancias-briefly/blob/main/services/instance-manager/src/access.ts): `services/instance-manager/src/access.ts`
- [App catalog policy](https://github.com/d1abloo/instancias-briefly/blob/main/packages/config/src/apps.ts): `packages/config/src/apps.ts`
- **Persistent state**

### Other components

- **User**
- **Linux node**

## Connections

- User → Web panel: uses (evidence: `README.md`)
- Web panel → Application API: requests
- Application API → Instance lifecycle API: routes lifecycle
- Instance lifecycle API → Node scheduler: enqueues work
- Node scheduler → Job queue: adds jobs (evidence: `services/scheduler/src/main.ts`)
- Node scheduler → Persistent state: selects and updates (evidence: `services/scheduler/src/main.ts`)
- Node scheduler → Instance manager: dispatches jobs
- Instance manager → Container provisioning: provisions (evidence: `services/instance-manager/src/main.ts`)
- Container provisioning → Linux node: runs isolated containers (evidence: `README.md`)
- Instance manager → Persistent state: records job state (evidence: `services/instance-manager/src/main.ts`)
- Cloud environments → Instance lifecycle API: loads cloud runtime (evidence: `apps/api/src/instances/cloud.controller.ts`)
- Cloud environments → Local cloud services: proxies cloud requests
- Deployments → Deployment worker: dispatches deployments
- Stacks → Stack orchestrator: orchestrates stacks
- Managed databases → Capacity policy: checks capacity (evidence: `apps/api/src/modules/databases/databases.service.ts`)
- Stacks → Capacity policy: checks capacity (evidence: `apps/api/src/modules/stacks/stacks.service.ts`)
- Instance lifecycle API → App catalog policy: validates app manifests
- Resource reconciler → Persistent state: sweeps resource state (evidence: `services/reconciler/src/main.ts`)
- Resource reconciliation → Persistent state: reconciles resources
- Metrics collection → Persistent state: stores metrics and logs (evidence: `services/metrics-worker/src/main.ts`)
- Terminal gateway → Persistent state: validates terminal claim (evidence: `services/terminal-gateway/src/main.ts`)
- Terminal gateway → Linux node: attaches terminal (evidence: `services/terminal-gateway/src/main.ts`)
- Resource access → Persistent state: manages access state
- Account and platform → Persistent state: manages account resources
- Administration → Persistent state: reads operations state
