user-engine/.claude/rules/architecture.md

## Architecture

Headless Engine (PIP) for users, accounts, and memberships. Same
authoritative inputs yield the same result. `access-engine` (`flex-auth`)
is the only decision point; this service supplies claims and enforces
results on its own mutations (PEP-shaped, same layer).

```text
verified IAM Profile claims
  -> UserEngineService (domain facts, projections, outbox)
  -> adapters: Postgres store, flex-auth /v1/check, tenant-engine,
     provisioning, registration verification, event/mail delivery
```

- `domain/` — persistence-neutral schemas. No HTTP, DB, or SDK imports.
- `ports.py` — adapter protocols (store, identity claims, authorization,
  provisioning, tenant management, secrets, outbox).
- `service.py` — headless API. Protected mutations go through `_authorize`
  then `_record_mutation` in one store transaction.
- `adapters/` — Postgres, flex-auth (fail-closed), OIDC claims, HTTP
  neighbors. `LocalAuthorizationCheckPort` is a standalone/test double.
- `runtime.py` / `web.py` — optional WSGI portal over the same APIs.
- `layer.yaml` + `pep-stance.yaml` — security-layer declaration and
  unreachable-engine stance.

Boundary contract:
`~/net-kingdom/canon/standards/user-engine-boundary-contract_v0.1.md`.

## Quick Reference

`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference