Skip to content

AGENTS.md

Latest commit

 

History

History
48 lines (36 loc) · 2.17 KB

AGENTS.md

File metadata and controls

48 lines (36 loc) · 2.17 KB

AGENTS.md

Purpose

This repository is a teaching showcase for a modern GraphQL-to-SQL stack using Apollo Server, Express, Prisma, TypeScript, SQLite, and a second upstream data source.

Repo Map

  • src/server.ts: process bootstrap, environment loading, shutdown wiring
  • src/app.ts: Express and Apollo assembly
  • src/config: environment parsing and logging
  • src/graphql: SDL files, typed context, and resolvers
  • src/services: domain services and upstream API client
  • src/data: Prisma client factory and repositories
  • prisma: Prisma schema, migrations, and seed script

Required Commands

  • npm run dev: local development server
  • npm run build: Prisma generate, GraphQL codegen, and TypeScript build
  • npm run typecheck: strict TypeScript verification
  • npm run lint: Biome checks
  • npm run format: Biome formatter
  • npm run test: Prisma generate, GraphQL codegen, and Vitest suite
  • npm run db:migrate: apply the committed migration set
  • npm run db:seed: seed the SQLite database

Generated Files Policy

  • src/generated/prisma/** is generated by npm run db:generate and should not be edited by hand.
  • src/graphql/__generated__/resolvers-types.ts is generated by npm run codegen and should not be edited by hand.
  • If a schema, context, or Prisma model changes, regenerate the relevant output and include the generated diff in the same change.
  • For new Prisma schema changes, create a development migration with npx prisma migrate dev --name <change> on Node 22, then commit the resulting migration files.

Workflow Guardrails

  • Keep GraphQL SDL in .graphql files and keep resolver functions thin.
  • Put persistence details in repositories and business behavior in services.
  • Prefer adding or updating tests alongside code changes.
  • Do not couple tests to Apollo internals when the HTTP boundary can be exercised instead.
  • Keep README examples aligned with the current schema and scripts.

Review Checklist

  • Build, typecheck, lint, and tests all pass.
  • Prisma and GraphQL generated files are up to date.
  • Environment variable changes are reflected in .env.example and README.
  • Public GraphQL examples in README match the current schema.