Visdom Cloud

Visdom Cloud is the multi-tenant control plane for Visdom, the FOSSASIA visualization tool for live, rich experiment data. It adds the pieces a hosted, team-based Visdom deployment needs but the open-source visdom server doesn't provide on its own: user accounts, workspaces, role-based team access, shareable invite links, scoped API keys, and billing — all sitting in front of the existing visdom UI.

The project is split into two services:

• gateway/ — a FastAPI backend that owns authentication, workspaces, memberships, shared links, API keys, and billing.
• frontend/ — a React + Vite console where users manage their account, workspaces, and team.

Status

This project is under active development. Milestone 1 and Milestone 2 (auth, workspaces, roles, sharing, the console UI, and now automated tests + CI) are complete; Milestone 3 will connect this control plane to a workspace-aware visdom server behind a single reverse-proxied origin.

Features

• Email/password authentication with short-lived JWT access tokens and rotating HTTP-only refresh cookies
• Workspaces with admin/member/viewer roles
• Two ways to add collaborators: direct email invites (the invitee must accept) and shareable join links (an admin must approve), both requiring explicit consent on both sides
• Invites work even for people who don't have an account yet — they're picked up automatically at registration
• API keys scoped to either an entire account or a hand-picked set of workspaces, with optional expiry
• A billing tab backed by a real plan/usage catalog (Free / Pro / Enterprise), with live plan switching — payment processing is not yet wired up
• A unified toast and confirm/prompt notification system shared visually with the upstream visdom project
• A "Visualizations" link from the console into the visdom server, and a link back, so the two apps can be navigated between today (a fully single-origin, session-sharing integration is planned for Milestone 3)

Getting started

Prerequisites

• Python 3.11+
• Node.js 20+
• A running PostgreSQL instance (for local development against SQLite, see Testing below)

Backend (gateway)

cd gateway
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# edit .env: set DATABASE_URL to your local Postgres instance and a real JWT_SECRET

python run.py

The gateway starts on http://localhost:8085 by default (configurable via PORT in .env). Database tables are created automatically on startup; Alembic is configured for future schema migrations as the project matures.

Frontend

cd frontend
npm install

cp .env.example .env
# edit .env if your gateway isn't running on the default port

npm run dev

The console starts on http://localhost:5173 and proxies /api requests to the gateway.

Testing

The gateway's test suite runs against an in-memory SQLite database, so no Postgres instance or .env file is required to run it:

cd gateway
pip install -r requirements.txt
pytest tests/ -v

The frontend does not yet have an automated test suite; npm run build is used as a compile-correctness check.

Linting

# Backend
cd gateway
ruff check .

# Frontend
cd frontend
npm run lint

Contributing

Contributions are welcome — see CONTRIBUTING.md for guidelines on issues, pull requests, and running tests/linters before you submit one.

License

This project is part of the FOSSASIA Visdom ecosystem. Licensing will be finalized to match the upstream visdom project.