The Problem

This repository provides a local cloud console for managing multi-cloud runtimes, but static analysis reveals significant architectural friction that impedes maintenance. The codebase suffers from circular import dependencies, oversized service files exceeding 1,000 lines, and duplicated adapter logic across cloud providers. These conditions create high cognitive load for engineers attempting changes and increase the risk of introducing regressions during feature development.

What This Does

Floci UI functions as a web console for a local multi-cloud runtime, rendering a unified Cloud Explorer and Console Home. The interface derives its data from the service catalog and adapter registry rather than static definitions; specifically, packages/frontend/src/features/cloud-console/CloudConsoleSections.tsx renders services based on GET /api/clouds/:cloud/services. The backend API in packages/api/ implements the logic via a hub-and-spoke pattern centered on packages/api/src/cloud-spi/types.ts, which 30 modules depend on (instability 0.03), and adapters in packages/api/src/adapter-aws/ that handle specific cloud operations. Runtime capabilities are defined in packages/api/src/cloud-spi/serviceCatalog.ts, with gaps noted, such as Azure Serverless returning 501 Not Implemented despite an registered adapter.

How It Is Wired

Control flows from the frontend entry point packages/frontend/src/App.tsx through HTTP requests to the API routes in packages/api/src/routes/. Requests route through service files like packages/api/src/services/ec2.ts (1,049 lines, high cognitive load) which delegate to cloud adapters. The import graph contains 147 internal modules connected by 207 edges. A critical cycle exists between packages/api/src/cloud-spi/types.ts, packages/api/src/cloud-spi/serviceCatalog.ts, and packages/frontend/src/features/ec2/SgRuleTable.tsx, meaning modules in this cycle are mutually reachable, complicating refactoring. The module packages/api/src/cloud-spi/errors.ts acts as a hub with 27 dependents and zero outports, making it a high-blast-radius point of change. Additionally, 269 repeated 6-line blocks exist across the AWS adapter files, indicating logic that should be extracted into shared helpers.

How To Use It

Setup:

docker compose up

For the full multi-cloud stack:

docker compose --profile multicloud up

Open http://localhost:4500 in a browser.

Configuration: No local environment configuration is required to run the containerized application. The README documents the docker compose commands as the primary entry point.

Running it: The application starts via the Docker Compose defined in docker-compose.yml. The backend API is initiated as a service within the compose file, and the frontend connects to the exposed port.

Real-World Use

A platform operator managing a hybrid environment can use this console to view both local AWS EC2 instances and GKE clusters in a single interface. By running cd packages/api && bun run scripts/service-matrix.ts, the operator can regenerate the service capability matrix, which lists which compute, storage, and networking services are available per cloud provider. If an Azure Functions endpoint is accessed, the UI will display a "coming soon" tooltip because the Floci-AZ runtime returns a 501, even though an adapter is registered, demonstrating how the console exposes real runtime state rather than mock data.

Code Health & Issues

The following findings are determined by static analysis and the SDLC audit:

  • HIGH - Pin third-party GitHub Actions to a commit SHA - .github/workflows (evidence: pnpm/action-setup@v6, oven-sh/setup-bun@v2; a tag can be moved, causing the action running with secrets to change unpredictably).
  • HIGH - Remove continue-on-error from steps that gate correctness - .github/workflows/ci.yml (line 66; a failing test suite could report a green check).
  • MEDIUM - Pin the container base image by digest - docker/Dockerfile (evidence: node:20-alpine, oven/bun:1-alpine, alpine:3; mutable tags mean build and runtime environments can drift without record).
  • MEDIUM - Gate pull requests on a dependency vulnerability scan - .github/workflows (evidence: no dependency scan in CI; this is the primary gate to catch known-vulnerable packages before build).
  • MEDIUM - Set persist-credentials: false on checkout - .github/workflows/ci.yml (evidence: checkout keeps the token, allowing later steps to read pushable credentials).
  • MEDIUM - Add a non-root USER to the image - docker/Dockerfile (evidence: no USER directive; a process running as root is root against every mounted volume).
  • LOW - Set timeout-minutes on the workflow jobs - .github/workflows/conventional-commits.yml (evidence: one workflow declares no job timeout, risking overlap on a two-hourly schedule).

The Bottom Line

The repository delivers a functional local cloud console that successfully aggregates real runtime data across multiple providers, which is a strong technical achievement. However, the codebase is held back by architectural debt—specifically circular dependencies and oversized files—that raises the cost of change, and SDLC hygiene gaps in GitHub Actions pinning and container security that should be addressed before onboarding new engineers or moving toward production use.