Fusion
61c5554c42
Commits merged: - docs(FN-019): complete Step 6 — documentation index, conversation handoff, project brief, and build config - test(FN-019): complete Step 4 — doc validation tests, project-brief.md, and fix mvp-scope placeholders - feat(FN-019): complete Step 3 — draft mvp-scope.md with milestones, dependency order, and open questions - docs(FN-019): fix auth callback flow, Python syntax, dev bypass clarity, add AccessProvider protocol and type stubs - feat(FN-019): complete Step 2 — draft enhanced architecture.md with all 18 required sections Files changed: docs/README.md | 11 +- docs/architecture.md | 1185 ++++++++++++++++++++++++++++++++++----- docs/conversation-handoff.md | 68 +++ docs/mvp-scope.md | 184 ++++++ docs/project-brief.md | 31 + package.json | 3 + tests/docs/__init__.py | 0 tests/docs/test_architecture.py | 120 ++++ 8 files changed, 1444 insertions(+), 158 deletions(-) Fusion-Task-Id: FN-019
Headquarter
Hosted workspace and tool-orchestration platform where authenticated users create projects, connect Git repositories, and spawn self-hosted tools such as RunFusion and code-server.
Current Status
This repository provides:
- React + Vite + TypeScript frontend (
apps/web) - FastAPI + Python backend (
apps/api) - Manifest-driven tool registry with built-in RunFusion and code-server definitions
- Root monorepo tooling (pnpm workspace, Makefile)
- Docker Compose local development stack
- Deployment skeleton for Portainer + Traefik
- Automated tests (Vitest + pytest)
Repository Layout
├── apps/
│ ├── web/ # React frontend
│ └── api/ # FastAPI backend
├── packages/ # Shared packages (future)
├── docs/ # Architecture, development, and deployment docs
├── deploy/ # Portainer/Traefik deployment examples
├── docker-compose.yml
├── docker-compose.traefik.yml
├── package.json # Root monorepo scripts
├── Makefile # Common local workflows
└── .env.example # Shared environment variables
Prerequisites
- Node.js ≥ 20 and pnpm ≥ 9
- Python ≥ 3.11
- Docker and Docker Compose (optional, for local Postgres)
Quickstart
# Install dependencies
make install
# Copy environment examples
cp .env.example .env
cp apps/web/.env.example apps/web/.env
# Run tests
make test
# Start frontend and backend in development mode
make dev
Docker Compose
docker compose up --build -d
This starts the API, web frontend, and PostgreSQL.
Commands
| Command | Description |
|---|---|
make install |
Install Node and Python dependencies |
make dev |
Start frontend and backend in parallel |
make test |
Run frontend and backend tests |
make lint |
Run linters |
make typecheck |
Run type checkers |
make build |
Build frontend and backend |
make compose-up |
Start Docker Compose stack |
make compose-down |
Stop Docker Compose stack |
Continuous Integration
All pull requests and pushes to main are validated by a GitHub Actions workflow (.github/workflows/ci.yml). The workflow runs the frontend and backend quality gates in parallel:
- Web CI — lint, typecheck, and test the React frontend.
- API CI — lint with
ruff, typecheck withmypy, and runpytestagainst a PostgreSQL service container.
See Development for details on running these checks locally.
Documentation
- Architecture — System design and MVP phases
- Development — Local setup and day-to-day commands
- Deployment — Portainer/Traefik assumptions
- Deploy Skeleton — Deployment file reference
Scope Boundaries
This scaffold intentionally defers detailed implementation to follow-up tasks:
- FN-004 — Backend domain models, database migrations, API endpoints, auth integration
- FN-005 — Frontend dashboard navigation, project creation, authenticated flows
- FN-006 — Full deployment automation, dynamic Traefik labels for spawned tool containers
- FN-003 — Manifest-driven tool registry
- FN-007 — Provider-independent Git connection model
- FN-008 — RunFusion executable environment proof of concept
- FN-009 — Persistent config and secrets handling
- FN-010 — code-server manifest and spawn flow
License
TBD