wild-pc/recommendations.md

Scaling Recommendations

1. Extract a shared library

The same patterns are already duplicated in central-context and notification-bridge: BaseSettings with .env, FastAPI lifespan boilerplate, uvicorn entry points, error-to-HTTP-exception translation, test fixtures with temp dirs and settings overrides. At dozens of services this becomes a maintenance problem — fix a bug in the pattern and you're patching it everywhere.

A castle-core (or similar) package that provides a base settings class, standard lifespan wiring, common test fixtures, and health check endpoint would let new services start from ~10 lines of setup code.

2. Standardize project layout

Right now there are three different layouts: src/central_context/, flat notification_bridge/, and single-file convert.py. Pick one (the src/ layout is the most robust) and stick with it. This matters because any top-level tooling that iterates over projects needs predictable structure.

3. Top-level task runner

With dozens of projects, there needs to be a way to run commands across all or some of them. A root Makefile, justfile, or script that can do things like:

• make test — run all tests
• make test p=central-context — run one project's tests
• make lint — lint everything
• make sync — uv sync in all projects

Without this, significant time gets spent just navigating and running repetitive commands.

4. Port and service registry

Ports are currently hardcoded defaults (9000, 9001). With dozens of services, there needs to be a single source of truth for port assignments — even if it's just a services.yaml at the repo root that maps service names to ports.

5. Inter-service configuration

notification-bridge hardcodes http://localhost:9000 as the central-context URL. This pattern doesn't scale — each new service that talks to another service adds more hardcoded URLs in more .env files. Consider either:

• A convention like CASTLE_{SERVICE_NAME}_URL derived from the registry
• A shared config that generates per-service .env files

6. Consistent ruff/pyright configuration

Each project currently has its own ruff rules (devbox-connect selects E,F,I,W while mboxer selects ALL). With dozens of projects, either put a shared ruff.toml at the repo root (ruff walks up to find config) or decide on one standard. Same for pyright — only devbox-connect has it enabled currently.

7. What to defer

• Containerization/orchestration — until deploying somewhere beyond the local machine
• API gateway / service mesh — premature until there are actual traffic patterns
• Distributed tracing / observability — add when debugging cross-service issues becomes painful
• Formal API schema sharing (OpenAPI contracts between services) — FastAPI generates these already; formalize when there are consumers that need stability guarantees

Priority

The highest-leverage first step is the shared library + top-level task runner, since those reduce the marginal cost of adding each new service.