pokemon-inventory/AGENTS.md

Agent Instructions

Mission

Build and maintain the Pokémon Inventory & Sales Reference Catalog according to the documentation in docs/.

The documentation is the source of truth. Do not invent requirements when an authoritative project rule exists.

Before changing code

1. Read the relevant documentation.
2. Identify affected domain modules and tests.
3. Preserve the Product → Inventory Item → Listing → Sale separation.
4. Check public/private data boundaries.
5. Check accessibility requirements.
6. Add or update automated tests with the change.

Architecture rules

• Use the modular-monolith architecture.
• Keep HTTP handling in routes.
• Keep application behavior in services.
• Keep business invariants in domain logic.
• Keep persistence in repositories.
• Keep external integrations behind provider/storage interfaces.
• Keep asynchronous work in the worker.
• Do not introduce microservices without an explicit architecture decision.
• Do not bypass the API from the browser.
• Do not put server-only business logic in shared browser packages.

Security

• The frontend is never the security boundary.
• Enforce authorization server-side.
• Use secure HttpOnly SameSite sessions.
• Never store authentication tokens in localStorage.
• Never commit credentials or secrets.
• Treat uploads, user input, and provider data as untrusted.

Domain rules

• Physical inventory copies are separate Inventory Item records.
• Provider mappings belong to Products, not physical copies.
• Sales are manual records; there is no checkout.
• Sold history is retained.
• Financial values use integer minor units.
• USD is the canonical stored/calculated currency.
• Public DTOs must never expose private financial, buyer, provider-debugging, or audit data.

Change discipline

Prefer small, focused changes. Avoid unrelated refactoring.

When a decision changes the architecture or requirements, update the relevant documentation before or with the implementation.