pikasTech-unidesk/docs/reference/repo-tree.md

• unidesk/ (Repository root: configuration, orchestration, CLI, and documentation)
  • AGENTS.md (Top-level agent index and scripts/cli.ts usage guide)
  • TEST.md (Manual CLI test plan following cli-spec expectations)
  • config.json (Single source of truth for ports, tokens, runtime, paths, and provider identity)
  • docker-compose.yml (Main server orchestration for database, backend-core, frontend, provider-gateway, and managed main-server user services such as Todo Note)
  • package.json / bun.lock (Root Bun tooling for CLI checks)
  • .gitignore
  • reference -> docs/reference (Compatibility symlink for older references)
  • scripts/ (Unified CLI and implementation modules)
    • cli.ts (Single Bun CLI entry)
    • tsconfig.json (TypeScript check scope for CLI)
    • src/ (CLI business logic modules; cli.ts remains a thin router)
      • config.ts (Root config loading and validation)
      • docker.ts (Docker Compose env generation, start/stop/status/logs)
      • jobs.ts (Fire-and-Forget job state under .state/jobs/)
      • check.ts (Formal checks)
      • debug.ts (Real-flow debug helpers)
      • command.ts (Bounded command execution helpers)
      • output.ts (JSON output helpers)
      • e2e.ts (Public frontend/provider ingress, internal core/database, and Playwright frontend E2E checks)
  • logs/ (Generated service logs; ignored by git)
  • .state/ (Generated job state and compose env; ignored by git)
  • docs/
    • issue/ (Manual test issue records)
    • reference/ (Long-term reference documents)
      • arch.md (Distributed work platform architecture)
      • repo-tree.md (This repository structure reference)
      • cli.md (CLI command model and async job contract)
      • config.md (Config and runtime rules)
      • deployment.md (Docker stack deployment and health criteria)
      • frontend.md (Frontend layout and design rules)
      • provider-gateway.md (Provider connection and host SSH maintenance bridge)
      • observability.md (Logs and status visibility)
      • e2e.md (Delivery gate, Playwright frontend E2E, and database persistence checks)
  • src/ (TypeScript component monorepo)
    • package.json (Component workspace metadata)
    • bun.lock (Component dependency lockfile)
    • tsconfig.base.json (Project references for component checks)
    • tsconfig.check.json (No-emit TypeScript check scope for all components)
    • components/
      • shared/ (Shared message types and utilities)
        • package.json
        • tsconfig.json
        • src/index.ts
      • backend-core/ (UniDesk stateless core service container)
        • package.json
        • tsconfig.json
        • Dockerfile
        • src/index.ts (Server setup, HTTP/WebSocket routing, startup orchestration)
        • src/types.ts (All interfaces and type aliases)
        • src/config.ts (Environment variable reading and config validation)
        • src/context.ts (Shared mutable state container: db client, config ref, dbReady flag)
        • src/logger.ts (Structured logger factory)
        • src/http.ts (HTTP/JSON utilities, ISO formatting, nested value extraction)
        • src/db.ts (Database init, schema creation, all CRUD queries)
        • src/performance.ts (Request/operation performance sampling and database size reporting)
        • src/provider-registry.ts (Provider WebSocket lifecycle: register, heartbeat, status, disconnect)
        • src/task-dispatcher.ts (Task creation, dispatch to providers, wait-for-result)
        • src/ssh-bridge.ts (SSH session bridging over provider WebSocket)
        • src/egress-tcp.ts (Egress TCP proxy for provider outbound connections)
        • src/scheduler.ts (Scheduled task system: cron-like recurring tasks)
        • src/microservice-proxy.ts (Microservice routing, HTTP proxy, health aggregation)
        • src/overview.ts (Overview endpoint, node/task/service summary, load test)
      • frontend/ (Frontend web application container)
        • package.json
        • tsconfig.json
        • Dockerfile
        • src/index.ts (Bun static server, login/session handling, and same-origin internal API proxy)
        • src/app.tsx (TypeScript + React browser app shell, login, global data loading, and route dispatcher; /app.js is generated by Bun at runtime)
        • src/todo-note.tsx (Todo Note user-service React page; do not fold back into app.tsx)
        • src/findjob.tsx (FindJob user-service React page; do not fold back into app.tsx)
        • src/pipeline.tsx (Pipeline user-service React page and React Flow control graph; do not fold back into app.tsx)
        • src/met-nonlinear.tsx (MET Nonlinear D601 training orchestration React page; do not fold back into app.tsx)
        • src/code-queue.tsx (Code Queue user-service React page; do not fold back into app.tsx)
        • src/oa-event-flow.tsx (Unified OA event flow and Trace/STEP stats React page; do not fold back into app.tsx)
        • src/k3sctl.tsx (K3S Control Plane React page backed only by k3sctl-adapter; do not fold back into app.tsx)
        • public/ (HTML/CSS static assets for the compact industrial console; no handwritten app JS)
      • provider-gateway/ (Compute node Provider Gateway container)
        • package.json
        • tsconfig.json
        • Dockerfile
        • src/index.ts (WebSocket client, heartbeat, system/Docker telemetry, Docker adapter, provider.upgrade handler, Host SSH / WSL SSH maintenance probe)
        • scripts/host-ssh-shell.sh (Optional maintenance-only SSH bridge)
      • database/ (PostgreSQL initialization and configuration)
        • config/postgresql.conf
        • init/001_unidesk_init.sql
      • microservices/ (UniDesk-owned user services and compatibility examples)
        • code-queue/ (Codex/OpenCode queue backend; k3s-managed when exposed through UniDesk)
        • oa-event-flow/ (Unified OA event ledger, tag stream, and Trace/STEP stats center)
        • k3sctl-adapter/ (D601 k3s control-plane adapter and managed service manifests)
        • example-service/