Developer setup

Run the FamilyCo monorepo locally for development.

This guide is for contributors and developers who want to build, modify, or run FamilyCo from source. End users should use the release builds instead.

Prerequisites

• Node.js 22 LTS
• pnpm 10
• A POSIX shell (macOS, Linux, or WSL on Windows)

1. Install dependencies

pnpm install

The repository is a pnpm workspace managed by Turborepo. Workspaces under apps/* and packages/* are linked automatically.

2. Configure environment

cp .env.example .env
cp apps/web/.env.example apps/web/.env

The web .env file is primarily needed when running the web client standalone (against an external server). The default local server URL is http://127.0.0.1:4000.

See Configuration for the full list of environment variables.

3. Run development mode

Server + Web

Runs the Fastify server and the Vue 3 web client together.

pnpm dev

Default endpoints:

• Web: http://127.0.0.1:5173
• Server: http://127.0.0.1:4000 (API at /api/v1)

Desktop (Electron)

Builds workspace packages and starts the web + Electron runtime.

pnpm dev:electron

The desktop shell embeds its own server and stores data in your OS user-data folder.

Everything in parallel

pnpm dev:p

Runs all dev tasks across the workspace in parallel. Useful when you want hot reload across packages too.

Common commands

Goal	Command
Run server + web	pnpm dev
Run web + electron	pnpm dev:electron
Build all packages	pnpm build
Build electron release	pnpm build:electron
Run all tests	pnpm test
Typecheck the workspace	pnpm typecheck
Generate the Prisma client	pnpm prisma:generate
Run a Prisma migration	pnpm prisma:migrate

Package-scoped examples:

pnpm --filter @familyco/server dev
pnpm --filter @familyco/web dev
pnpm --filter @familyco/electron dev

Validation gates

Before opening a pull request, run at minimum:

pnpm -w typecheck
pnpm --filter @familyco/server test
pnpm --filter @familyco/web build

For broader changes:

pnpm build
pnpm test

Troubleshooting

Port 4000 is already in use

Stop stale server processes (or change PORT in .env) and rerun pnpm dev.

Electron native module mismatch after Node/runtime upgrade

Rebuild native modules and restart desktop mode:

pnpm --filter @familyco/electron rebuild:native
pnpm dev:electron

Server is in read-only mode

Migration safety failed at startup. Check the server logs, fix the database state, then restart. While in read-only mode, mutation routes return 503 READ_ONLY_MODE.

Next steps

Architecture

Monorepo layout, runtime lanes, and design constraints.

Coding rules

Conventions for AI agents and human contributors.

Domain model

Core entities and invariants enforced by the schema.

Configuration

Environment variables for runtime, queue, auth, and more.