# Contribution Guide

## 1. Coding Standards

- Use TypeScript with `strict` mode enabled; no `any` types.
- Import order: core libs → third-party → project aliases (`@/`) → relative.
- Naming: PascalCase for components, camelCase for functions/variables, UPPER_SNAKE_CASE for constants.
- Add JSDoc comments for all public APIs and exported types.
- Line length ≤ 120 characters; use Prettier for formatting (`frontend/prettier.config.cjs`).
- Run `npm run lint` and fix all warnings before opening a PR.

## 2. Branch Workflow

- Create a feature branch: `git checkout -b feat/<short-description>`
- Keep branches up to date with `main` via `git rebase`.
- Submit a Pull Request with a clear title and description.
- Ensure the PR passes CI (tests, lint, type-check).
- Address review comments promptly.

## 3. Running Tests

```bash
# Install dependencies
cd frontend && npm install

# Run tests in watch mode
npm run test

# Run tests once (CI)
npm run test:run

# Type-check
npx tsc --noEmit
```

## 4. Making Your First Contribution

1. Pick a beginner-friendly issue labeled `good first issue`.
2. Read [ARCHITECTURE.md](ARCHITECTURE.md) to understand the relevant module.
3. Make a small, focused change; avoid refactoring unrelated code.
4. Run the relevant tests and confirm they pass.
5. Commit and push, then open a PR with a clear description of what and why.

## 5. Where to Extend

| Goal | Where to look |
| --- | --- |
| Add a new node type | `src/lib/graph/nodeTypeBuilder.ts` + `registerBuiltinNodes.tsx` |
| Add a new output/render type | `src/lib/graph/configTypes.ts` + `rendering.ts` |
| Change canvas state shape | `src/app/canvas/canvasStore.ts` + reducer + tests |
| Add a new Logos block | `src/app/recollections/logos/logosSchema.ts` |
| Add a backend endpoint | `backend/src/routes/` → `services/` → `index.ts` |

## 6. Useful Links

- [ARCHITECTURE.md](ARCHITECTURE.md) — architecture overview, key patterns, module map
- [PERFORMANCE_IMPROVEMENTS.md](PERFORMANCE_IMPROVEMENTS.md) — bottleneck analysis and improvement plan
- [docs/CODE_REVIEW_CHECKLIST.md](docs/CODE_REVIEW_CHECKLIST.md) — PR review checklist
- [docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md](docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md) — node plugin system design

*Thank you for contributing!*