> ## Documentation Index
> Fetch the complete documentation index at: https://familyco.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/quickstart) instead.

## Prerequisites

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

## 1. Install dependencies

```bash theme={null}
pnpm install
```

The repository is a [pnpm workspace](https://pnpm.io/workspaces) managed by [Turborepo](https://turbo.build/). Workspaces under `apps/*` and `packages/*` are linked automatically.

## 2. Configure environment

```bash theme={null}
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](/guides/configuration) for the full list of environment variables.

## 3. Run development mode

<Tabs>
  <Tab title="Server + Web">
    Runs the Fastify server and the Vue 3 web client together.

    ```bash theme={null}
    pnpm dev
    ```

    Default endpoints:

    * Web: `http://127.0.0.1:5173`
    * Server: `http://127.0.0.1:4000` (API at `/api/v1`)
  </Tab>

  <Tab title="Desktop (Electron)">
    Builds workspace packages and starts the web + Electron runtime.

    ```bash theme={null}
    pnpm dev:electron
    ```

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

  <Tab title="Everything in parallel">
    ```bash theme={null}
    pnpm dev:p
    ```

    Runs all `dev` tasks across the workspace in parallel. Useful when you want hot reload across packages too.
  </Tab>
</Tabs>

## 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:

```bash theme={null}
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:

```bash theme={null}
pnpm -w typecheck
pnpm --filter @familyco/server test
pnpm --filter @familyco/web build
```

For broader changes:

```bash theme={null}
pnpm build
pnpm test
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port 4000 is already in use">
    Stop stale server processes (or change `PORT` in `.env`) and rerun `pnpm dev`.
  </Accordion>

  <Accordion title="Electron native module mismatch after Node/runtime upgrade">
    Rebuild native modules and restart desktop mode:

    ```bash theme={null}
    pnpm --filter @familyco/electron rebuild:native
    pnpm dev:electron
    ```
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="Architecture" icon="diagram-project" href="/concepts/architecture">
    Monorepo layout, runtime lanes, and design constraints.
  </Card>

  <Card title="Coding rules" icon="ruler" href="/guides/coding-rules">
    Conventions for AI agents and human contributors.
  </Card>

  <Card title="Domain model" icon="database" href="/concepts/domain-model">
    Core entities and invariants enforced by the schema.
  </Card>

  <Card title="Configuration" icon="sliders" href="/guides/configuration">
    Environment variables for runtime, queue, auth, and more.
  </Card>
</Columns>