No description
  • Python 98.9%
  • Dockerfile 1.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-05-30 20:33:17 -04:00
app Cleaning up naming and added a readme 2026-05-30 20:29:19 -04:00
.env.example Cleaning up naming and added a readme 2026-05-30 20:29:19 -04:00
.gitignore Adding git ignore to strip .env file 2026-05-30 20:33:17 -04:00
docker-compose.yml Cleaning up naming and added a readme 2026-05-30 20:29:19 -04:00
Dockerfile Initial commit of agentic code based on spec 2026-05-30 20:24:18 -04:00
filesystem-service-spec.md Initial commit of agentic code based on spec 2026-05-30 20:24:18 -04:00
pyproject.toml Initial commit of agentic code based on spec 2026-05-30 20:24:18 -04:00
README.md Cleaning up naming and added a readme 2026-05-30 20:29:19 -04:00
uv.lock Initial commit of agentic code based on spec 2026-05-30 20:24:18 -04:00

Interface Hub Workspaces

A lightweight REST API that exposes a virtual filesystem over HTTP, backed by PostgreSQL. Users get their own folder trees with arbitrary nesting. Folders and files can be shared with other users; sharing a folder cascades visibility to its entire subtree automatically.

Built with FastAPI and asyncpg, managed with uv, deployed via Docker Compose.


Quick start

docker compose up --build

The API is available at http://localhost:8000.

  • Interactive docs (Swagger UI): http://localhost:8000/docs
  • Read-only docs (ReDoc): http://localhost:8000/redoc
  • Raw OpenAPI schema: http://localhost:8000/openapi.json

Local development

uv sync                                        # create .venv and install all dependencies
cp .env.example .env                           # configure database URL if needed
uv run uvicorn app.main:app --reload           # start with hot-reload

The service expects a running Postgres instance. The easiest way to get one is to start only the database container:

docker compose up postgres

Then run the service locally with uv run uvicorn ... above. On startup it runs the SQL migrations automatically, so the schema is always up to date.

Common uv commands

Command Purpose
uv sync Install/update deps from lockfile, recreate .venv if needed
uv add <package> Add a runtime dependency and update the lockfile
uv add --dev <package> Add a dev-only dependency
uv run <command> Run a command inside the managed virtual environment
uv run pytest Run the test suite
uv run ruff check . Lint
uv run ruff format . Format

Authentication

There is no authentication layer. The service is designed to run on a trusted local network. Users are bare identifiers — access-scoped endpoints identify the acting user via the X-User-Id: <id> request header.


API overview

Users

Method Path Description
POST /users Create a user
GET /users List all users
GET /users/{user_id} Get a user
DELETE /users/{user_id} Delete a user and all their nodes

Nodes (files & folders)

Method Path Description
POST /nodes Create a file or folder (X-User-Id becomes owner)
GET /nodes/{node_id} Get node metadata
GET /nodes/{node_id}/content Get raw text content (files only)
PATCH /nodes/{node_id} Rename, move, edit content, or update tags
DELETE /nodes/{node_id} Delete node and its subtree (owner only)
GET /nodes/{node_id}/children List direct children
GET /nodes/{node_id}/shares List shares on a node (owner only)
GET /me/roots Acting user's owned roots + nodes shared directly with them
GET /me/tree Full accessible tree; optional ?depth=N to limit levels

Shares

Method Path Description
POST /shares Share a node with another user (owner only)
PATCH /shares Change a share's permission level (owner only)
DELETE /shares?node_id=&shared_with_id= Remove a share (owner only)
Method Path Description
GET /search?q= Case-insensitive substring search across accessible file content

Project structure

.
├── app/
│   ├── main.py          # FastAPI app, lifespan (pool + migrations on startup)
│   ├── config.py        # Settings loaded from environment / .env
│   ├── db.py            # asyncpg pool, migration runner, shared FastAPI dependencies
│   ├── migrations.sql   # Idempotent DDL — run on every startup
│   ├── models.py        # Pydantic request/response models
│   ├── queries.py       # All SQL — accessible CTE, node/user/share/search operations
│   └── routers/
│       ├── users.py     # /users
│       ├── nodes.py     # /nodes, /me/roots, /me/tree
│       ├── shares.py    # /shares
│       └── search.py    # /search
├── Dockerfile           # uv-based image (ghcr.io/astral-sh/uv:python3.12-bookworm-slim)
├── docker-compose.yml   # postgres (pgvector/pgvector:pg17) + service
├── pyproject.toml       # Project metadata and dependencies
├── uv.lock              # Pinned dependency lockfile
└── .env.example         # Template for local environment configuration

Key design points

Single table for files and folders. Both are rows in nodes. type is either "file" or "folder". A folder may never have content; a file may have null/empty content.

Cascade sharing via recursive CTE. Every access-scoped query starts with:

WITH RECURSIVE accessible(id) AS (
    SELECT id FROM nodes WHERE owner_id = $1          -- owned nodes
    UNION
    SELECT node_id FROM shares WHERE shared_with_id = $1  -- directly shared
    UNION
    SELECT n.id FROM nodes n JOIN accessible a ON n.parent_id = a.id  -- subtrees
)

Sharing a folder writes one row to shares; descendants become visible at read time for free.

Cascade deletes in the database. parent_id and shares both use ON DELETE CASCADE, so deleting a folder removes its entire subtree and all related share records in one statement.

Content search. ILIKE with a pg_trgm GIN index — fast substring matching, stays in-database, upgradeable to full-text search later.


Environment variables

Variable Default Description
DATABASE_URL postgresql://ws_user:ws_pass@postgres:5432/workspace asyncpg connection string
DB_POOL_MIN 1 Minimum pool connections
DB_POOL_MAX 10 Maximum pool connections

Copy .env.example to .env and edit as needed for local development.


Database

The schema is defined in app/migrations.sql and applied idempotently on every startup (CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS). No migration tool is needed — re-running the file is always safe.

Tables: users, nodes, shares.

The pgvector extension is installed and reserved for a future RAG/embedding phase. The pg_trgm extension powers content search.