---
title: Development Guide
description: Set up a local development environment and contribute to Sencho.
---

## Prerequisites

- **Node.js 22** or later
- **Docker** and **Docker Compose** installed and running
- **Git**

---

## Setup

```bash
# Clone the repository
git clone https://github.com/AnsoCode/Sencho.git
cd Sencho

# Install backend dependencies
cd backend && npm install

# Install frontend dependencies
cd ../frontend && npm install
```

---

## Running in development

Open two terminal windows:

**Terminal 1 — Backend** (Express + nodemon, port 3000):

```bash
cd backend
npm run dev
```

**Terminal 2 — Frontend** (Vite dev server, port 5173):

```bash
cd frontend
npm run dev
```

The Vite dev server proxies all `/api` and `/ws` requests to `localhost:3000`, so you access the app at `http://localhost:5173`.

On first boot, you'll see a setup screen to create an admin account.

<Note>
  The backend requires a Docker socket to be available. On macOS and Linux this is `/var/run/docker.sock`. On Windows, ensure Docker Desktop is running.
</Note>

---

## Running tests

### Backend unit tests (Vitest)

```bash
cd backend
npm test
```

Runs all test files in `src/__tests__/`. Each test file runs in an isolated forked process with its own database instance.

### End-to-end tests (Playwright)

```bash
# From the project root
npm run test:e2e
```

E2E tests run against a live development instance (backend on port 3000, frontend on port 5173). Make sure both are running before executing tests.

For interactive test debugging:

```bash
npm run test:e2e:ui
```

---

## Code style

- **TypeScript** with `strict: true` in both packages. No `any` casts or `@ts-ignore`.
- **ESLint 9** flat config. Run `npm run lint` in both `backend/` and `frontend/` directories.
- **Frontend styling:** Tailwind CSS with [shadcn/ui](https://ui.shadcn.com/) components. See the design system section in `CLAUDE.md` for color, typography, and component patterns.
- **Backend patterns:** Express route handlers in `src/index.ts`, business logic in `src/services/`. All new endpoints must use `authMiddleware`. SQL must use parameterized queries.

---

## Pull request workflow

1. Create a branch from `main` (e.g. `feat/my-feature`, `fix/my-bug`)
2. Use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages:
   - `feat:` — new user-facing feature (bumps minor version)
   - `fix:` — bug fix (bumps patch version)
   - `docs:` — documentation changes (no version bump)
   - `chore:`, `ci:`, `refactor:`, `test:`, `perf:` — internal changes (no version bump)
3. Update `CHANGELOG.md` under `## [Unreleased]` for user-facing changes
4. Update or create documentation in `/docs` if behavior changes
5. Open a PR targeting `main`
6. Ensure CI passes before requesting review

Keep PRs focused — one feature or fix per PR.

---

## Project structure

```
Sencho/
├── backend/              # Express.js API + Docker orchestration
│   ├── src/
│   │   ├── index.ts      # Route definitions (monolithic)
│   │   ├── services/     # Business logic (17 services)
│   │   └── __tests__/    # Vitest unit tests
│   └── package.json
├── frontend/             # React 19 + Vite SPA
│   ├── src/
│   │   ├── components/   # UI components
│   │   ├── context/      # React context providers
│   │   ├── lib/          # Utilities (apiFetch, etc.)
│   │   └── App.tsx       # Root router
│   └── package.json
├── docs/                 # Mintlify documentation site
├── e2e/                  # Playwright E2E test specs
├── Dockerfile            # Multi-stage production build
├── docker-compose.yml    # Quick-start deployment
└── package.json          # Root scripts (test, test:e2e)
```

For more detail on how the components relate, see the [Architecture Overview](/reference/architecture).