Repository Guidelines

Project Structure & Module Organization

• docs/ holds runbooks and deployment notes; update alongside code changes.
• search-service/ is the Bun microservice. Within it:
  • src/index.ts boots the Hono app from src/app.ts.
  • src/routes/*.ts define HTTP endpoints; keep filenames lower-case.
  • src/middleware/, src/utils/, src/types/ host shared concerns—reuse before creating new helpers.
  • src/sync/ orchestrates Mongo ↔ Elasticsearch jobs and must stay idempotent.
  • src/__tests__/ contains Bun test suites (*.test.ts) mirroring module paths.
  • scripts/ ships operational tooling; deploy/ maintains Cloud Run/ECS manifests; dist/ is generated output.

Build, Test, and Development Commands

Run from search-service/:

bun install          # install dependencies
bun run dev          # watch-mode API on :3000
bun run build        # emit production bundle in dist/
bun test             # execute Bun tests
bun run typecheck    # strict TypeScript check
bun run biome:check  # lint + format verification
docker-compose up -d elasticsearch kibana  # optional local stack
bun scripts/migrate-index.ts --dry-run     # preview ES mapping changes

Coding Style & Naming Conventions

• TypeScript with ES modules and strict typings; export DTOs from src/types.
• Biome enforces 2-space indentation, double quotes, and sorted imports—run bun run biome:fix instead of hand-formatting.
• Use camelCase for symbols, PascalCase for classes/types, and UPPER_SNAKE env keys; keep route and script filenames lower-case.
• Centralize shared middleware under src/middleware and prefer composable functions over monolithic handlers.

Testing Guidelines

• Place unit and integration specs in src/__tests__ following the feature.test.ts naming scheme.
• Cover happy paths, validation failures, and external dependency errors.
• Elasticsearch-dependent specs expect the docker-compose stack; guard them if services are unavailable.
• Before opening a PR, ensure bun test and bun run typecheck pass locally.

Commit & Pull Request Guidelines

• Use Conventional Commits (feat:, fix:, chore:) as referenced in CI_CD_SETUP.md.
• Husky hooks block AI-assistant mentions and run lint-staged plus bun run typecheck; resolve hook failures before retrying.
• PRs should include a concise summary, validation notes (commands + outcomes), linked issues, and screenshots or curl snippets for API changes.
• Update relevant docs (docs/*.md, docs/INDEX_MIGRATION.md) whenever behavior or operations change.

Security & Configuration Tips

• Never commit .env*, .mcp.json, or internal guides; hooks will reject them.
• Treat .env.example as configuration truth; store secrets in GitHub Actions or local .env.
• Coordinate updates to scripts/*.ts, deploy/*.json, and .github/workflows when changing Elasticsearch or Cloud Run settings.