Quick Start

This guide will get Flowstate Canvas running on your local machine. You’ll start the backend services, seed demo data, and launch both the web and desktop apps.

Contact your administrator for repository access, credentials, and environment setup details before following this guide.

Prerequisites

Before you begin, make sure you have these tools installed:

Required Software

• Docker Desktop: Version 20.10 or later. Download from docker.com.
• Node.js: Version 22 or later. Download from nodejs.org or use a version manager like nvm.
• pnpm: Version 10 or later. Install with npm install -g pnpm or brew install pnpm on macOS.
• just: Command runner for development tasks. Install with brew install just on macOS or cargo install just if you have Rust installed.
• Secrets management tooling: Required to inject development secrets. Contact your administrator for setup instructions.

Verify Installation

Run these commands to verify everything is installed correctly:

docker --version
# Should show: Docker version 20.10.0 or later

node --version
# Should show: v22.0.0 or later

pnpm --version
# Should show: 10.0.0 or later

just --version
# Should show: 1.0.0 or later

If any command fails, install the missing tool before continuing.

Secrets Setup

Flowstate injects secrets at runtime via your team’s secrets management solution. This keeps sensitive values out of the repository while making development seamless.

Contact your administrator to:

• Gain access to the development secrets vault
• Configure your local secrets management tooling
• Verify you can resolve development credentials before proceeding

Clone the Repository

If you haven’t already, clone the Flowstate Canvas repository:

git clone https://github.com/your-org/flowstate-canvas.git
cd flowstate-canvas

Install Dependencies

Install all Node.js dependencies with pnpm:

pnpm install

This will install dependencies for all apps and packages in the monorepo. It may take a few minutes on the first run.

Start Services

Start all backend services with Docker:

just up

This command starts Docker containers for the backend, web app, database, cache, and object storage, then waits for services to become healthy.

Leave this terminal window open. The logs will stream here.

Verify Services

Open a new terminal and check that all services are running:

docker compose ps

You should see all containers in the “Up” state.

Initialize the Database

Push the Prisma schema to the database:

just db-push

This creates all collections and indexes. You’ll see output confirming the schema was applied.

Seed Demo Data

Populate the database with demo data:

just db-seed

This creates demo users, rooms, offices, and sample canvas data you can use to explore the platform. Contact your administrator for the demo account credentials.

Access the Web App

Open your browser and navigate to the web app URL configured for your environment (see your administrator for the local URL). Sign in with one of the demo accounts provided during setup.

After signing in, you’ll land on the canvas. You should see several tiles representing Rooms, Offices, and other entities. Try clicking, dragging, and interacting with them.

Start the Desktop App

The desktop app runs outside Docker (it needs GPU and display access). Start it with:

just desktop

This launches the Electron app in development mode. The app will open in a new window. Sign in with the same demo account you used for the web app.

The desktop app connects to the same backend services, so your canvas state syncs between web and desktop.

Service Overview

When running locally, the following services are available (exact URLs depend on your environment configuration — see your administrator):

Service	Purpose
Web App	Main web interface
Desktop SPA	Electron renderer dev server
Backend REST API	Internal REST API (proxied by web)
RPC Gateway	Public RPC API (used by desktop)
MongoDB	Database
Redis	Cache and pub/sub
Object Storage	File storage (MinIO or S3)
Prisma Studio	Database GUI (when running)

Common Commands

Here are the most useful just commands for daily development:

Service Management

just up          # Start all services
just down        # Stop all services
just restart     # Restart all services
just rebuild     # Rebuild Docker images (use after dependency changes)

Logs

just logs              # View logs from all services
just logs-backend      # View backend logs only
just logs-web          # View web logs only

Database

just db-push           # Push Prisma schema to MongoDB
just db-seed           # Seed demo data
just db-studio         # Open Prisma Studio
just db-reset          # Reset database (WARNING: deletes all data)
just db-generate       # Regenerate Prisma client

Desktop App

just desktop           # Start desktop app in dev mode
just desktop-restart   # Restart desktop app
just desktop-stop      # Stop desktop app

Shell Access

just shell-backend     # Open shell in backend container
just shell-db          # Open database shell
just redis-cli         # Open Redis CLI

Type Checking

# Run TypeScript checks in Docker containers
docker compose exec backend pnpm tsc --noEmit
docker compose exec web pnpm astro check

Building

# Build apps in Docker containers
docker compose exec backend pnpm build
docker compose exec web pnpm build

Troubleshooting

Secrets / Environment Errors

Problem: Services fail to start with missing environment variable errors.

Solution: Verify your secrets management tooling is configured correctly and you have access to the development vault. Contact your administrator if access is missing.

Docker Issues

Problem: Containers fail to start or show “unhealthy” status.

Solution:

1. Check Docker Desktop is running
2. Verify you have enough resources allocated (4GB RAM minimum, 8GB recommended)
3. Stop all containers: just down
4. Remove volumes: docker compose down -v
5. Rebuild images: just rebuild
6. Start again: just up

Port Conflicts

Problem: Services fail to start with “port already in use” errors.

Solution:

1. Identify the conflicting process using lsof -i :<port> with the port shown in the error
2. Stop the conflicting process or update the port mapping in docker-compose.yml

Database Connection Errors

Problem: Backend logs show “failed to connect to MongoDB” or “ECONNREFUSED”.

Solution:

1. Verify the database container is running: docker compose ps mongodb
2. Check database logs: docker compose logs mongodb
3. Try restarting the database: docker compose restart mongodb
4. If that fails, reset the database: just db-reset (WARNING: deletes all data)

Desktop App Won’t Start

Problem: just desktop fails or the app crashes on launch.

Solution:

1. Verify Node.js version: node --version (must be 22+)
2. Reinstall dependencies: pnpm install
3. Clear Electron cache: rm -rf apps/desktop/.vite
4. Check the terminal logs for specific errors

Real-Time Sync Not Working

Problem: Changes don’t sync between web and desktop, or tiles don’t move in real-time.

Solution:

1. Verify Redis is running: docker compose ps redis
2. Check Redis logs: docker compose logs redis
3. Test Redis connection: just redis-cli then run PING (should return “PONG”)
4. Restart backend to reconnect to Redis: docker compose restart backend

Build Errors After Pulling Changes

Problem: After pulling new code, builds fail with missing dependencies or type errors.

Solution:

1. Reinstall dependencies: pnpm install
2. Regenerate Prisma client: just db-generate
3. Rebuild Docker images: just rebuild
4. Push schema changes: just db-push
5. Restart all services: just down && just up

Next Steps

Now that Flowstate is running locally, here’s what to explore next:

Explore the Platform

• Sign in with different demo accounts to see how multi-user collaboration works
• Create a new Room and add Sparks to it
• Set up an Office and invite other demo users
• Try moving tiles around the canvas and watch them sync between web and desktop
• Open the widget store and install a widget

Read the Documentation

• Architecture Overview: Understand how the system is built
• The Canvas: Learn how the infinite canvas works
• Data Model: Explore the database schema and relationships

Start Developing

• Check out the development guides in the sidebar
• Read AGENTS.md in the repository root for coding standards and workflows
• Join the team chat to ask questions and share ideas

Getting Help

If you run into issues not covered here:

1. Check the logs: just logs shows output from all services
2. Search the repository issues on GitHub
3. Ask in the team Slack or Discord channel
4. Review the AGENTS.md file for detailed development guidelines

Welcome to Flowstate Canvas development. Happy building!