user-engine/docs/development.md

Development

Stack

The initial implementation uses Python 3.12 and the standard library. The first slice intentionally avoids runtime dependencies so the repository can be tested immediately in local and agent environments.

Layout

src/user_engine/
  domain/      transport- and persistence-neutral domain schemas
  ports.py     adapter protocols for identity, authorization, events, audit,
               membership export, application bindings, and secrets
  testing/     local fixtures for tests and examples
tests/         standard-library unittest suite

The domain layer should not import HTTP frameworks, database clients, or platform-specific SDKs. Those integrations belong behind ports.

Commands

make test

The command runs:

PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'

Implementation Rule

Add new behavior in this order:

1. domain schema or port;
2. local fixture or adapter;
3. test that proves the boundary;
4. infrastructure adapter or API surface.