Add Service

Add service

Adds a new service (business logic, e.g. blog, finance, auth) to the framework so generated projects can select it via aegis init --services or add it later via aegis add-service. Traced from the two most recent services, blog and finance.

When to use

Use when the task is "add a new service to Aegis Stack" (a business capability under app/services/<name>/, selected via include_<name> in copier.yml).

Do NOT use for adding a component (infrastructure: worker, scheduler, database, redis, ingress, observability) - components live in aegis/core/components.py and share the same PluginSpec shape but a different file footprint. Do NOT use for changing behavior inside an existing service; that is ordinary feature work, not this skill.

Files that change

Registry (ServiceSpec is a thin alias of PluginSpec pinned to kind=SERVICE; see aegis/core/plugins/spec.py):

• aegis/core/services.py: add a ServiceSpec entry to the SERVICES dict. Set type (add a new ServiceType member only if none fit), description/long_description, required_components, recommended_components, pyproject_deps, template_files (display list), marker_path (the path aegis update uses to detect the service on disk), and docs_path (leave "" until the docs page ships - a non-empty value is pinned by tests/core/test_spec_docs_paths.py).
• aegis/core/services.py: wiring=PluginWiring(...) on the spec - declares routers (RouterWiring), dashboard_cards/dashboard_modals (FrontendWidgetWiring), and deps_providers (SymbolWiring). This metadata mirrors, and must stay in sync with, the hand-written Jinja conditionals in the template files below - it does not currently drive their rendering for in-tree services.
• aegis/core/services.py: files=FileManifest(primary=[...], extras={...})
  • every path the service owns. primary is the add/init base; compute_file_mapping() derives post_gen_tasks.get_component_file_mapping() from this, so there is no separate hand-maintained mapping to edit.
• aegis/core/migration_generator.py: only if the service owns tables, add a ServiceMigrationSpec and reference it from the spec's migrations=[...] list in services.py. The spec has no tables in it: a revision's contents are derived from the SQLModel classes by the generated project's app/cli/migrate_gen.py (run by init/add inside the project venv), so a column is declared in exactly one place, the model. The spec carries only what models cannot express - service_name, description, the Postgres schema its tables live in, and data_sql for a row a schema change makes mandatory. MIGRATION_SPECS is derived lazily from every spec's .migrations via collect_migrations() - no dict entry to hand-maintain.
• aegis/constants.py: AnswerKeys - add <NAME> = "include_<name>" and SERVICE_<NAME> = "<name>". Add any sub-flag keys the service needs (see FINANCE_PLAID, FINANCE_SNAPTRADE, FINANCE_IMPORT).
• copier.yml (repo root, not under templates/): add the include_<name> bool question, plus any per-service config questions gated with when: "{{ include_<name> }}" (model on finance_plaid). Extend get_services_needing_migrations (aegis/core/migration_generator.py) if the service owns tables, and the two template mirrors of that rule (pyproject.toml.jinja's alembic dependency, database_init.py.jinja); tests/core/test_alembic_dependency_matches_migrations.py fails until they agree.
• aegis/core/<name>_service_parser.py: only if the service takes bracket syntax like <name>[option] (model on ai_service_parser.py, auth_service_parser.py, insights_service_parser.py; blog and finance need none of this - they have no options= on their spec). Wire it into aegis/core/service_resolver.py if it introduces a cross-service dependency check (see the insights[per_user] requires auth[org] block).
• aegis/cli/interactive.py: interactive_<name>_service_config() only if the service needs an interactive config prompt during aegis add-service --interactive (model on interactive_ai_service_config; not needed for blog/finance).

Generation and update plumbing (thread the new AnswerKeys.<NAME> answer key through the generate and update flows; a table-owning service that skips these generates fine but breaks migrations on aegis update):

• aegis/core/template_generator.py: add an AnswerKeys.<NAME>: "yes"/"no" entry to the answer dict built from selected_services (model on the existing per-service entries using extract_base_service_name).
• aegis/core/copier_manager.py: add AnswerKeys.<NAME> to the template context booleans, and if the service owns tables include it in the needs_migration_files detection.
• aegis/core/copier_updater.py and aegis/commands/update.py: add include_<name> = answers.get(AnswerKeys.<NAME>, False) and OR it into the aggregate migration/needs check used during update.
• aegis/core/manual_updater.py: add AnswerKeys.<NAME> to the answer-keys list it threads through add/remove.

CLI (framework commands, not the generated project's CLI):

• aegis/commands/add_service.py: resolves service deps to components, prompts for config, calls ManualUpdater.add_component, generates migrations via generate_migration/bootstrap_alembic. Only add a service-specific branch here if the service needs bracket-syntax parsing or extra answer keys threaded through (auth, ai, insights do; blog and finance need none).
• aegis/commands/remove_service.py: calls ManualUpdater.remove_component; no per-service branch needed unless the service needs a custom warning (see the auth-specific data-loss warning block).
• aegis/commands/services.py: the aegis services list command reads SERVICES/ServiceType automatically; no edit needed unless a new ServiceType header is required.

Template (aegis/templates/copier-aegis-project/{{ project_slug }}/):

• app/services/<name>/: the service package (business logic, deps.py for the FastAPI dependency provider referenced by wiring.deps_providers).
• app/components/backend/api/<name>/: routes, registered in app/components/backend/api/routing.py.jinja behind a full-body {%- if include_<name> %} import + app.include_router(...) block.
• app/cli/<name>.py.jinja: the project's <name> subcommand. Register it in app/cli/main.py.jinja with the existing try: importlib.import_module(...) / except ImportError: pass pattern.
• Dashboard card: app/components/frontend/dashboard/cards/<name>_card.py, exported from cards/__init__.py.jinja behind {%- if include_<name> %}, and added to the aggregate {%- if include_auth or ... or include_<name> or _plugins %} gate in that same file (guards ServicesCard's import).
• Dashboard modal: app/components/frontend/dashboard/modals/<name>_modal.py, exported from modals/__init__.py.jinja, and added to the modal_map and import block in dashboard/cards/card_utils.py.jinja (key convention: "service_<name>", matching wiring.dashboard_cards[0].modal_id).
• The card/modal also need registering in the surrounding frontend wiring, each behind {%- if include_<name> %}: dashboard/status_overview.py.jinja (the status grid), app/components/frontend/main.py.jinja (the frontend app that mounts the card), app/services/system/ui.py.jinja (dashboard registry), and app/components/backend/api/deps.py.jinja if the service's routes need a shared dependency. Trace how blog appears in each before adding <name>.
• app/components/backend/startup/component_health.py.jinja: register the service's health check behind {%- if include_<name> %} with register_service_health_check("<name>", check_<name>_service_health).
• app/components/backend/startup/database_init.py.jinja (table-owning services only): import the service's SQLModel models behind {%- if include_<name> %} (with # noqa: F401), add include_<name> to the needs_migrations set expression, and add a "<name>": ("table", "<table>") entry to the existing-table stamp map. Skipping this means the service's tables are never created or stamped.
• alembic/env.py.jinja (table-owning services only): import the models behind {%- if include_<name> %} so Alembic autogenerate sees them.
• pyproject.toml.jinja: gate service-specific dependencies behind {%- if include_<name> %}. If the service owns tables, add it to the shared alembic==1.16.5 gate condition (the big {%- if include_auth or ... or include_<name> %} line).
• docs/services/<name>/ under the template tree is a separate, optional convention (ships docs inside the generated project itself); only comms has it today. Do not treat it as required.

Framework docs (this repo's own /docs, published via the root mkdocs.yml

• distinct from the template docs above, and what ServiceSpec.docs_path points at):

• docs/services/<name>/index.md (+ cli.md, api.md, dashboard.md, examples.md, setup.md as applicable - see docs/services/blog/ and docs/services/payment/ for the current shape).

• mkdocs.yml (repo root): add a Services: - <Name>: nav block pointing at the new pages (see the blog/payment/insights entries).

• aegis/core/services.py: set docs_path="services/<name>" on the spec once the pages exist (leave "" until then, per above).

Tests (generated-project template tests, under aegis/templates/copier-aegis-project/{{ project_slug }}/):

• tests/services/<name>/test_<name>_service.py (or tests/services/test_<name>_service.py for a small service): unit tests for the service's business logic (write first, TDD).
• tests/api/test_<name>_endpoints.py: only if the service exposes routes.
• Template-render test (framework side, optional): if the service's template has non-trivial cross-service Jinja branching (e.g. blog's router renders differently with auth on/off/rbac), add a tests/core/test_<name>_template_render.py that renders the .jinja file directly via Environment(loader=FileSystemLoader(get_template_path())) and asserts on the rendered source (see tests/core/test_blog_template_render.py).

Tests (this repo's own CLI/core test suite):

• tests/core/test_services.py: add a spec-shape test class (name, type, required/recommended components, pyproject_deps) and a test_<name>_service_wiring test asserting spec.wiring.routers[0].module, .alias, and the dashboard modal_ids (mirrors test_blog_service_wiring).
• tests/cli/test_services_cli.py: extend the aegis services list-command coverage tables with the new service's expected inclusion/exclusion flags.
• tests/cli/conftest.py: add a <name>_with_database (or similarly named) entry to NAMED_PROJECT_SPECS so downstream tests copy a cached project instead of regenerating one (tests/CLAUDE.md explains the cache; skipping this entry costs 10+ minutes of CI time). Also add the new stack to tests/cli/test_stack_generation.py's STACK_COMBINATIONS and to the everything entry in NAMED_PROJECT_SPECS.
• tests/cli/test_add_service_importable.py: add the service name (with bracket options if it would otherwise prompt interactively) to SERVICE_INVOCATIONS. This is the regen-gap guard: it runs aegis add-service <name> against a cached base project and imports the webserver/CLI/routing entry chains in the generated project's own venv, catching files that render fine at init time but are missing from the add/remove file mapping.
• A migration test in the style of tests/cli/test_add_service_migrations.py if the service owns tables (asserts aegis add-service <name> bootstraps alembic and writes the migration file).
• Collateral: adding a service to SERVICES shifts the service list that several existing tests assert against. Expect to update tests/cli/test_guided.py, tests/cli/test_interactive_project_selection.py, tests/cli/test_interactive_scheduler.py, tests/cli/test_ai_configuration.py, and tests/cli/test_scheduler_persistence.py when they fail on counts or expected-option lists. These are not new files; run the gates and fix what goes red.

i18n:

• aegis/i18n/locales/en.py: add "service.<name>" (short description, used by aegis services) and "projectmap.<name>" (label used by the project map renderer) with the real English strings.
• aegis/i18n/locales/{de,es,fr,ja,ko,ru,zh,zh_hant}.py: add the SAME two keys to every other locale, using the English string as a placeholder. This is required for parity: tests/core/test_i18n.py asserts every locale carries the same keys as English and fails naming the missing key otherwise. Real translation of the placeholders is a separate translator-reviewed pass; do not attempt it here, but the keys must exist now.

Cross-cutting:

• Shared files need no registration. A shared file is any template path no component/service FileManifest claims; aegis add/remove finds it by rendering the tree at the old and new answers and diffing. Add {% if include_<name> %} conditionals to routing.py.jinja, component_health.py.jinja, cards/__init__.py.jinja — or to a brand-new shared file — and it is handled automatically. There is no list to add it to. tests/core/test_shared_scope_completeness.py fails, naming the file, if a stack-dependent file somehow ends up handled by nothing.