- Python 98.9%
- Dockerfile 1.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| app | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| filesystem-service-spec.md | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
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) |
Search
| 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.