svc-tenders Service Shell Composition

Purpose

This note records the current service-shell composition of services/svc-tenders/src/server.ts after Cleanup Sprint 21.

It is not an ownership document for all domains in svc-tenders.

It is a shell-composition map:

• what the file bootstraps
• what it wires
• what it composes directly
• what remains transitional or unresolved

Labels used here:

• VERIFIED
• REAL
• TRANSITIONAL
• UNRESOLVED

Composition zones

1. Bootstrap / runtime setup

Status:

• VERIFIED
• REAL
• stable shell composition

Purpose:

• initialize runtime config
• create DB pool
• initialize shared storage/runtime dependencies
• create the Express app

What is wired here:

• resolveConfig() from services/svc-tenders/src/config.ts
• createPool(...) from services/svc-tenders/src/db.ts
• DeclarationEvidenceStorage from services/svc-tenders/src/evidenceStorage.ts
• multer(...) declaration evidence upload middleware
• express.json(...)

Future planning implication:

• this is legitimate service-shell runtime setup
• there is no reason to treat this zone as domain ownership

2. Repository / handler composition

Status:

• VERIFIED
• REAL
• mixed stable + transitional composition

Purpose:

• instantiate the persistence and command-side surfaces passed into route modules

What is wired here:

• root mixed repository:
  • new TendersRepository(...)
  • services/svc-tenders/src/repository.ts
• dedicated child repositories:
  • new TenderRepository(...)
  • new AuctionRepository(...)
  • new DeclarationRepository(...)
  • new IcpiRepository(...)
  • new ButkhuziRepository(...)
  • new OutputAllocationsRepository(...)
• non-repository runtime collaborators:
  • new VacancyCommandHandlers(...)
  • new AccommodationCommandHandlers(...)
  • new VacancyReadRepository(...)
  • new AccommodationReadRepository(...)
  • new AccommodationOwnerReadRepository(...)

What is stable:

• direct child repository use for:
  • tenders
  • auctions
  • declarations
  • ICPI
  • Butkhuzi

What is still transitional:

• the root TendersRepository is still instantiated because:
  • KES persistence still lives there
  • legacy compatibility residue still lives there
  • unresolved cross-domain methods still live there

Future planning implication:

• the shell already shows which route groups have dedicated repositories
• future extraction work should continue reducing root TendersRepository use, not hide it

3. Shared infra boundary

Status:

• VERIFIED
• REAL
• stable shell-owned infra boundary

Purpose:

• hold shared infra/runtime pieces that are not route-local

What is wired here:

• declaration evidence upload middleware
• declaration evidence storage
• runtime key/config validation

Why this stays shell-owned:

• depends on runtime config and global request handling constraints
• not meaningfully owned by one route module

Future planning implication:

• keep this distinction explicit so future AI sessions do not confuse upload/storage setup with declaration-domain ownership

4. Transitional composition aliases

Status:

• VERIFIED
• TRANSITIONAL

Purpose:

• make mixed composition explicit without pretending it is already cleanly extracted

What is wired here:

1. declarationEvidenceUploadRunner

• built from the shared multer instance via services/svc-tenders/src/routes/support/declarationUploadSupport.ts

2. auctionDeclarationRepository

• composed locally from:
  • services/svc-tenders/src/repository/outputAllocations.ts
  • services/svc-tenders/src/declaration/repository.ts

Why this is transitional:

• auction declaration routes need both:
  • declaration-owned methods
  • unresolved output_allocations methods
• that composition is real, but it is not a clean final ownership story

Future planning implication:

• this is one of the most important unresolved composition zones in the shell
• future extraction should treat it as explicit mixed composition, not as proof that one side owns the whole surface

5. Route-support wiring

Status:

• VERIFIED
• REAL
• stable composition layer

Purpose:

• adapt service-shell helpers into route-local support contracts

What is wired here:

• vacancyRouteSupport
• accommodationRouteSupport
• icpiRouteSupport
• butkhuziRouteSupport
• kesRouteSupport
• tenderRouteSupport
• tenderDeclarationRouteSupport
• auctionRouteSupport
• auctionDeclarationRouteSupport

Backed by:

• services/svc-tenders/src/routes/support/

Why this matters:

• support wiring is not the same as repository ownership
• a route may have a clean support contract while still depending on transitional repository composition

Future planning implication:

• this layer is now a clean seam for future route extraction or shell reduction

6. Route registration

Status:

• VERIFIED
• REAL

Purpose:

• register route groups with explicit repository/handler/support inputs

What is registered here:

• vacancy routes via services/svc-tenders/src/routes/registerVacancyRoutes.ts
• accommodation routes via services/svc-tenders/src/routes/registerAccommodationRoutes.ts
• ICPI routes via services/svc-tenders/src/routes/registerIcpiRoutes.ts
• Butkhuzi routes via services/svc-tenders/src/routes/registerButkhuziRoutes.ts
• KES routes via services/svc-tenders/src/routes/registerKesRoutes.ts
• tender routes via services/svc-tenders/src/routes/registerTenderRoutes.ts
• tender declaration routes via services/svc-tenders/src/routes/registerTenderDeclarationRoutes.ts
• auction routes via services/svc-tenders/src/routes/registerAuctionRoutes.ts
• auction declaration routes via services/svc-tenders/src/routes/registerAuctionDeclarationRoutes.ts

What is now clearer:

• which route groups use dedicated child repositories directly
• which route groups still use mixed root hosting
• where transitional composition is injected explicitly

7. Shell helper zone

Status:

• VERIFIED
• REAL

Purpose:

• keep remaining legitimate service-shell helpers in one place

Sub-boundaries:

1. auth/principal shell helpers

• bearer extraction
• JWT validation
• /auth/me principal resolution

2. low-level shared parser helpers

• small parsing primitives still used across support builders

3. KES ingress/security helpers

• third-party KYC boundary checks
• incoming payload signature verification

Reference:

• docs/SVC_TENDERS_SERVER_SHELL_BOUNDARY.md

Future planning implication:

• no obviously route-local helper bodies remain stranded here
• future changes should be driven by boundary truth, not file length

Stable vs transitional vs unresolved

Stable

• runtime/bootstrap setup
• route-support wiring
• direct route registration using dedicated repositories
• shell helper grouping

Transitional

• continued root TendersRepository hosting for KES and compatibility residue
• declaration upload runner composition from shell-owned multer storage
• shell-level parser sharing across multiple route-support builders

Unresolved

• auction declaration route composition still depends on both:
  • declaration repository ownership
  • output allocation repository ownership
• root repository remains the service host for:
  • KES persistence
  • unresolved settlement bridge
  • compatibility residue

Practical reading guide for server.ts

Open services/svc-tenders/src/server.ts in this order:

1. bootstrap/runtime setup
2. repository/handler composition
3. shared infra boundary
4. transitional composition aliases
5. route-support wiring
6. route registration
7. shell helpers

That order reflects the real shell composition more truthfully than reading it as one flat file.