# Repository Guidelines

These notes align current contributors around the code layout, daily commands, and collaboration habits that keep `@samanhappy/mcphub` moving quickly.

## Project Structure & Module Organization

- Backend services live in `src`, grouped by responsibility (`controllers/`, `services/`, `dao/`, `routes/`, `utils/`), with `server.ts` orchestrating HTTP bootstrap.
- `frontend/src` contains the Vite + React dashboard; `frontend/public` hosts static assets and translations sit in `locales/`.
- Jest-aware test code is split between colocated specs (`src/**/*.{test,spec}.ts`) and higher-level suites in `tests/`; use `tests/utils/` helpers when exercising the CLI or SSE flows.
- Build artifacts and bundles are generated into `dist/`, `frontend/dist/`, and `coverage/`; never edit these manually.

## Build, Test, and Development Commands

- `pnpm dev` runs backend (`tsx watch src/index.ts`) and frontend (`vite`) together for local iteration.
- `pnpm backend:dev`, `pnpm frontend:dev`, and `pnpm frontend:preview` target each surface independently; prefer them when debugging one stack.
- `pnpm build` executes `pnpm backend:build` (TypeScript to `dist/`) and `pnpm frontend:build`; run before release or publishing.
- `pnpm test`, `pnpm test:watch`, and `pnpm test:coverage` drive Jest; `pnpm lint` and `pnpm format` enforce style via ESLint and Prettier.

## Coding Style & Naming Conventions

- TypeScript everywhere; default to 2-space indentation and single quotes, letting Prettier settle formatting. ESLint configuration assumes ES modules.
- Name services and data access layers with suffixes (`UserService`, `AuthDao`), React components and files in `PascalCase`, and utility modules in `camelCase`.
- Keep DTOs and shared types in `src/types` to avoid duplication; re-export through index files only when it clarifies imports.

## Testing Guidelines

- Use Jest with the `ts-jest` ESM preset; place shared setup in `tests/setup.ts` and mock helpers under `tests/utils/`.
- Mirror production directory names when adding new suites and end filenames with `.test.ts` or `.spec.ts` for automatic discovery.
- Aim to maintain or raise coverage when touching critical flows (auth, OAuth, SSE); add integration tests under `tests/integration/` when touching cross-service logic.

## Commit & Pull Request Guidelines

- Follow the existing Conventional Commit pattern (`feat:`, `fix:`, `chore:`, etc.) with imperative, present-tense summaries and optional multi-line context.
- Each PR should describe the behavior change, list testing performed, and link issues; include before/after screenshots or GIFs for frontend tweaks.
- Re-run `pnpm build` and `pnpm test` before requesting review, and ensure generated artifacts stay out of the diff.

## DAO Layer & Dual Data Source

MCPHub supports **JSON file** (default) and **PostgreSQL** storage. Set `USE_DB=true` + `DB_URL` to switch.

### Key Files

- `src/types/index.ts` - Core interfaces (`IUser`, `IGroup`, `ServerConfig`, etc.)
- `src/dao/*Dao.ts` - DAO interface + JSON implementation
- `src/dao/*DaoDbImpl.ts` - Database implementation
- `src/db/entities/*.ts` - TypeORM entities
- `src/db/repositories/*.ts` - TypeORM repository wrappers
- `src/utils/migration.ts` - JSON-to-database migration

### Modifying Data Structures (CRITICAL)

When adding/changing fields, update **ALL** these files:

| Step | File                       | Action                       |
| ---- | -------------------------- | ---------------------------- |
| 1    | `src/types/index.ts`       | Add field to interface       |
| 2    | `src/dao/*Dao.ts`          | Update JSON impl if needed   |
| 3    | `src/db/entities/*.ts`     | Add TypeORM `@Column`        |
| 4    | `src/dao/*DaoDbImpl.ts`    | Map field in create/update   |
| 5    | `src/db/repositories/*.ts` | Update if needed             |
| 6    | `src/utils/migration.ts`   | Include in migration         |
| 7    | `mcp_settings.json`        | Update example if applicable |

### Data Type Mapping

| Model          | DAO               | DB Entity      | JSON Path                |
| -------------- | ----------------- | -------------- | ------------------------ |
| `IUser`        | `UserDao`         | `User`         | `settings.users[]`       |
| `ServerConfig` | `ServerDao`       | `Server`       | `settings.mcpServers{}`  |
| `IGroup`       | `GroupDao`        | `Group`        | `settings.groups[]`      |
| `SystemConfig` | `SystemConfigDao` | `SystemConfig` | `settings.systemConfig`  |
| `UserConfig`   | `UserConfigDao`   | `UserConfig`   | `settings.userConfigs{}` |

### Common Pitfalls

- Forgetting migration script → fields won't migrate to DB
- Optional fields need `nullable: true` in entity
- Complex objects need `simple-json` column type