costco-grocery-list/docs/AGENTIC_CONTRACT_MAP.md

Agentic Contract Map (Current Stack)

This file maps PROJECT_INSTRUCTIONS.md architecture intent to the current repository stack.

Current stack

• Backend: Express (backend/)
• Frontend: React + Vite (frontend/)

Contract mapping

API Route Handlers (app/api/**/route.ts intent)

Current equivalent:

• backend/routes/*.js
• backend/controllers/*.js

Expectation:

• Keep these thin for parsing/validation and response shape.
• Delegate DB and authorization-heavy logic to model/service layers.

Server Services (lib/server/* intent)

Current equivalent:

• backend/models/*.js
• backend/middleware/*.js
• backend/db/*

Expectation:

• Concentrate DB access and authorization logic in these backend layers.
• Avoid raw DB usage directly in route files unless no service/model exists.

Client Wrappers (lib/client/* intent)

Current equivalent:

• frontend/src/api/*.js

Expectation:

• Centralize fetch/axios calls and error normalization here.
• Always send credentials/authorization headers as required.

Hooks (hooks/use-*.ts intent)

Current equivalent:

• frontend/src/context/*
• frontend/src/utils/* for route guards

Expectation:

• Keep components free of direct raw network calls where possible.
• Favor one canonical state propagation mechanism per concern.

Notes

• This map does not force a framework migration.
• It defines how to apply the contract consistently in the existing codebase.