Instruction Files — Turning AI Coding Assistants Into Team-Aware Engineers

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "file": ".github/copilot-instructions.md"
    },
    {
      "pattern": "**/*.test.ts",
      "file": ".github/instructions/testing-ts.md"
    },
    {
      "pattern": "db/migrations/**",
      "file": ".github/instructions/migrations.md"
    }
  ]
}

## Package Boundaries

Never import packages under `staging/src/` from outside the `staging/` tree.
Each `staging/` package is published as an independent Go module; treat it as
an external dependency and import the published module path instead.

## API Types

New API fields belong in the internal type file (`pkg/apis/<group>/types.go`)
and require a corresponding entry in the versioned conversion file before they
appear in a versioned API. Do not add fields directly to versioned structs.

## Error Responses

Use `k8s.io/apimachinery/pkg/api/errors` for constructing API error responses.
Do not return raw `errors.New()` or `fmt.Errorf()` from any function that
writes an HTTP response.

## Django Import Ordering

Follow Django's four-block import convention enforced by isort with
`--profile django`. Blocks in order:
1. Python standard library
2. Django (`django.*`)
3. Third-party packages
4. Local app imports (relative)

Never mix blocks. A blank line separates each block.

## Model Layout

Within a Django model class, order members as follows:
1. Field definitions (alphabetical within type groups)
2. `Meta` inner class
3. `__str__`
4. `save` override (if any)
5. `get_absolute_url` (if any)
6. Custom methods (alphabetical)

## Backwards Compatibility

Any change to a public Django API must work without modification for users
on the two previous feature releases. If a behaviour must change, add a
`RemovedInDjango<NN>Warning` deprecation warning for one full release cycle
before removing the old behaviour.

## Naming

- Variables and functions: `camelCase`
- Constructors and React components: `PascalCase`
- True module-level constants: `SCREAMING_SNAKE_CASE`
- Never use a leading underscore to indicate "private". If something should
  not be accessed externally, enforce it structurally (closure, module scope,
  WeakMap) rather than by naming convention.

## Destructuring

When accessing more than one property from an object, always destructure:

```js
// ✅
const { name, email, role } = user;

// ❌
const name = user.name;
const email = user.email;
const role = user.role;
```

When a function accepts three or more named parameters, use a destructured
options object instead of positional arguments.

## Callbacks

Use arrow functions for inline callbacks. Never use `.bind(this)` in JSX;
use class properties with arrow functions or hooks instead.

## Unsafe Code

Every `unsafe` block must be preceded by a comment that:
1. Explains why the operation is safe at this call site
2. Names the invariant being upheld
3. References any relevant documentation or prior art

Example:
```rust
// SAFETY: `ptr` was allocated by `Box::new` on line 42 and ownership
// was transferred via `Box::into_raw`. We are the sole owner and the
// pointer has not been freed.
unsafe { Box::from_raw(ptr) }
```

Never write a bare `unsafe { ... }` block without a SAFETY comment.
A CI check enforces this; the build will fail without it.

## Adding Shared Types

Only add types to `rustc_middle` if they are consumed by more than one
compiler pass. If a type is only used within a single pass, define it in
that pass's crate.

## Service Boundaries

All HTTP services must use FastAPI with the dependency injection patterns
established in `services/api/`. Specifically:

- Dependencies (database sessions, auth context, feature flags) are injected
  via FastAPI's `Depends()` mechanism, not imported as module globals.
- Never import `db_session` directly. Always receive it as a parameter:
  `db: AsyncSession = Depends(get_db)`.

The reason: module-global state makes async services unpredictable under
concurrent requests and makes unit testing require monkeypatching. Dependency
injection keeps each request's state isolated and makes dependencies explicit
in the function signature.

## File Organisation (Python Services)

```
services/<service-name>/
├── api/          ← FastAPI routers only (no business logic)
├── models/       ← SQLAlchemy ORM models
├── schemas/      ← Pydantic request/response schemas
├── services/     ← Business logic (no HTTP, no ORM)
├── repositories/ ← Database queries (returns domain objects, not ORM instances)
└── tests/
    ├── unit/     ← No I/O; all dependencies mocked
    └── integration/ ← Real database, no network calls to external services
```

Never put business logic in routers. Routers call service functions; service
functions call repository functions. The dependency direction is strict:
`api → services → repositories → models`.

## HTTP Client

Use `httpx.AsyncClient` for all outbound HTTP calls. Do not use `requests`,
`aiohttp`, or `urllib`. The `httpx` client is configured with default timeouts
and retry behaviour in `shared/http.py`; use `get_http_client()` from that
module rather than instantiating `httpx.AsyncClient` directly.

## Logging

Use `structlog` with the configuration from `shared/logging.py`. Never call
`logging.getLogger()` directly. Log at INFO level for significant business
events, DEBUG for implementation detail. Log statements must include a
`request_id` bound variable; it is injected automatically by the middleware
in `shared/middleware.py`.

## Naming Conventions

### Database and API

- Database columns: `snake_case`
- API request/response fields: `camelCase` (Pydantic models use `model_config =
  ConfigDict(alias_generator=to_camel)` for automatic conversion)
- Do not expose database column names directly in the API; define explicit
  Pydantic schemas with intentional field names.

### Event Names

Domain events follow the pattern `<Noun><PastTenseVerb>`, for example:
`UserRegistered`, `OrderShipped`, `PaymentFailed`. Never use present tense
(`UserRegisters`) or imperative (`RegisterUser`) for event names.

### Feature Flags

Feature flag names use `kebab-case` and follow the pattern
`<area>-<feature>-<state>`, for example: `checkout-new-pricing-enabled`,
`api-rate-limiting-active`. Register new flags in `config/feature_flags.py`
before using them in code.

## Testing

All tests use `pytest` with `pytest-asyncio` for async code. Do not use
`unittest.TestCase` or `asyncio.run()` in tests.

### Test Naming

Test functions follow the pattern `test_<unit>_<scenario>_<expected_outcome>`:

```python
# ✅
def test_create_user_with_duplicate_email_raises_conflict_error():
def test_get_order_when_not_found_returns_404():

# ❌
def test_user_creation():
def test_order():
```

### Fixtures

Fixtures are defined in `conftest.py` at the closest common ancestor of the
tests that use them. Use `scope="function"` by default. Only widen to
`scope="session"` for fixtures that establish a real database connection.

### Marks

- `@pytest.mark.integration` — test requires a running database
- `@pytest.mark.slow` — test takes more than 2 seconds
- `@pytest.mark.external` — test calls an external service

The CI fast-feedback loop excludes `integration`, `slow`, and `external` tests.
Run them locally with `pytest -m "integration or slow or external"`.

<!-- ❌ Vague — the agent already knows this -->
Write clean, readable code with good error handling.

<!-- ✅ Specific — encodes a convention the agent could not infer -->
All user-facing error messages must go through `errors.UserError(code, message)`
where `code` is a string from the enum in `errors/codes.py`. Never return a
raw exception message to the caller; those are logged internally but never
surfaced to the API response.

## Repository Return Types

Repository methods return domain objects, not ORM instances. Use dataclasses
or Pydantic models defined in `models/domain/`.

```python
# ✅ Repository method returns a domain object
async def get_user(self, user_id: UUID) -> User:
    row = await self.db.get(UserRow, user_id)
    return User(id=row.id, email=row.email, created_at=row.created_at)

# ❌ Do not return ORM rows from repository methods
async def get_user(self, user_id: UUID) -> UserRow:
    return await self.db.get(UserRow, user_id)
```

<!-- ❌ Rule without context — agent may misapply it at edges -->
Don't add retry logic in service clients.

<!-- ✅ Rule with context — agent understands why and won't fight the rule -->
Don't add retry logic in individual service clients. All retry behaviour
is centralised in `shared/resilience.py` using a token-bucket rate limiter.
Putting retries in service clients causes cascading thundering-herd failures
during outages; centralising them lets us tune retry budgets globally and
observe retry rates in one place.

# Copilot Instructions

This repository contains a FastAPI microservice for order management.
Python 3.12+. PostgreSQL 16 via asyncpg. All async; no synchronous I/O.

## Architecture

Strict layered architecture. Dependency direction: `api → services → repositories → models`.
Never import across layers in the wrong direction.

- `api/` — FastAPI routers. No business logic. Route handlers call service functions.
- `services/` — Business logic. No ORM, no HTTP. Calls repository functions.
- `repositories/` — Database access. Returns domain objects (not ORM rows).
- `models/` — SQLAlchemy ORM models (internal only) and Pydantic domain objects.

## Dependencies

Inject all shared dependencies via FastAPI's `Depends()`:
- Database session: `db: AsyncSession = Depends(get_db)` from `shared/db.py`
- Auth context: `user: AuthUser = Depends(require_auth)` from `shared/auth.py`
- Feature flags: `flags: FeatureFlags = Depends(get_flags)` from `shared/flags.py`

Never import `db_session`, `current_user`, or `feature_flags` as module globals.

## HTTP Client

Use `get_http_client()` from `shared/http.py`. Do not instantiate `httpx.AsyncClient` directly.

## Error Handling

Raise `errors.UserError(code, message)` for errors that should be returned to the caller.
All other exceptions are caught by the global exception handler, logged with the request ID,
and returned as a generic 500. Never return raw exception messages in API responses.

## Testing

- Framework: `pytest` + `pytest-asyncio`. No `unittest.TestCase`.
- Test names: `test_<unit>_<scenario>_<expected_outcome>`
- Fast tests (no I/O): `tests/unit/`
- Database tests: `tests/integration/`, marked `@pytest.mark.integration`
- Run fast tests: `pytest tests/unit/`
- Run all tests: `pytest -m "integration" --run-integration`