Project Knowledge

We use the repository pattern for all database access.
Each entity has its own repository class that extends BaseRepository.
Repositories handle all SQL queries — services never write raw SQL.
Here's an example from our codebase:

class UserRepository(BaseRepository[User]):
    async def find_by_email(self, email: str) -> User | None:
        return await self.find_one({"email": email})

Please read the coding standards from our wiki at
https://internal-wiki.example.com/coding-standards
and create rules from them.

Read the patterns in src/shared/base-repository.ts
and create a wiki page documenting the repository pattern we use.

Add a section about connection pooling.
We use a max of 20 connections per service instance.

Create a new wiki page about our error handling strategy.
All domain errors should extend AppError. HTTP errors are mapped
in the error middleware, not in individual handlers.

Create a rule: all Python files must use absolute imports.
No relative imports allowed except in __init__.py files.

Update this rule to also require that every new endpoint
has at least one integration test.

Merge Milestone 3 ("Migrate user authentication") and
Milestone 4 ("Migrate session management") into a single milestone.
They're tightly coupled and should be done together.

Our project follows clean architecture. The layers are:
- Domain (entities, value objects, repository interfaces)
- Application (use cases, DTOs, application services)
- Infrastructure (database repos, external API clients, message handlers)
- Presentation (controllers, middleware, request/response models)

Dependencies point inward. Infrastructure depends on Domain,
never the reverse. Use dependency injection everywhere.

Create a rule: never use console.log in production code.
Use the logger service from src/shared/logger.ts for all logging.
Debug logs should use logger.debug(), errors should use logger.error()
with the full error object.

The user service calls the billing service over gRPC.
The proto files are in shared/proto/billing.proto.
When migrating user-related code, preserve all billing
service calls and use the generated Python client from
shared/generated/billing_pb2_grpc.py.