Sprinting Solo

The parts store

The factory's parts are patterns: solutions to problems that recur in every business application. We took them from Sprinting's own production systems, made them independent of technology, and build them into every exo.

P-1

Environments and zones

Code and people must always know which environment they are in, and whether it is production.

exo1 · appliedexo2 · appliedexo3 · applied

The solution

  • Every environment has a short name (lcl, tst, prd), and the name is the only setting.
  • The zone (prod or nonp) is derived from the name in one place in the code; nothing crosses the zone line.
  • Dangerous operations such as test data and error details refuse to run in the prod zone.

How it fits together

  1. ENV_NAME"tst" | "prd" | ...zoneOf()
  2. zoneOf()zone = nonp | prodConfig
  3. ENV_NAME<app>-<type>-<env>ResourceNames
  4. Configenv + zone on every lineLogs
  5. Configrefuses zone = prodSeed
P-2

Layered configuration

Settings differ per environment, and some behaviour must change without a new deploy.

exo1 · partlyexo2 · partlyexo3 · partly

The solution

  • One schema with types and defaults; the application will not start with invalid configuration.
  • Layers from default through zone and environment to the process environment; secrets come from the host's secret store.
  • Feature toggles are a separate, small mechanism – one for the whole platform.

How it fits together

  1. Schemadefaults + typesAppConfig
  2. ZoneFileoverrides (nonp | prod)AppConfig
  3. EnvFileoverrides (tst, prd, ...)AppConfig
  4. ProcessEnvoverridesAppConfig
  5. SecretStoresecrets at runtimeProcessEnv
  6. AppConfigtyped, validated at startupCode
  7. ToggleServicetoggle(name, tenant) with cached ETag; default in codeCode
P-3

Test data

Every developer, test and test environment needs the same known data, and production must never get test data.

exo1 · partlyexo2 · partlyexo3 · partly

The solution

  • Seed data loads automatically and idempotently after migrations – never in the prod zone.
  • Fixed ids and named test personas with known roles, the same for developers, agents and tests.
  • Tests isolate themselves instead of sharing a database.

How it fits together

  1. Migrationsschema + reference data (all zones)Database
  2. Zonenonp only, else refuseSeed
  3. Seedtest orgs, users, records (fixed ids, upsert)Database
  4. Realm(nonp)named personas (admin, member, viewer)Tests
  5. Seedsame personas as rows + constantsTests
  6. Testsclean schema per fileDatabase
P-4

Traceable errors

Connect what the user saw to what the server logged, without leaking internals.

exo1 · partlyexo2 · partlyexo3 · partly

The solution

  • Every request gets an id, and every log line carries environment, zone, request and tenant.
  • One error contract (RFC 9457 Problem Details) and one global filter that hides details in production.
  • Secrets are masked before logging, and an agent can look up an error reference in the logs.

How it fits together

  1. Browserrequest + client trace id headerAPI
  2. APIrequest id, user, tenantRequestContext
  3. RequestContextevery line carries env, zone, request id, tenantLogs
  4. APIexception (context data + debug data)ErrorFilter
  5. ErrorFilterfull error, redactedLogs
  6. ErrorFilterProblem Details + request idBrowser
  7. User"it failed, ref 7f3c…"Agent
  8. Agentlookup by request idLogs
P-5

Separated customer data

One organisation must never see another's data – on any query.

exo1 · appliedexo2 · appliedexo3 · partly

The solution

  • Every owned row has an organisation key, and the scope comes from one source per request.
  • The service always filters on the scope through a shared layer, so it cannot be forgotten.
  • Every endpoint is tested for organisation B being unable to read or change organisation A's data.

How it fits together

  1. Tokenuser (issuer, sub)PermissionGuard
  2. PathorganisationIdPermissionGuard
  3. Membershiprole of user in organisationPermissionGuard
  4. PermissionGuardallowed, scope = organisationIdService
  5. ServiceWHERE organisation_id = scopeDatabase
P-6

Users from the identity provider

Create and link the application's users from the identity provider without manual steps or accidental access.

exo1 · appliedexo2 · appliedexo3 · applied

The solution

  • The identity provider proves who someone is; the application decides what they may do.
  • Users are created on first sign-in and keyed on the provider's stable id, not the e-mail.
  • Invited users are linked only with a verified e-mail, and new users get no permissions automatically.

How it fits together

  1. IdPiss, sub, email, email_verifiedToken
  2. TokenBearerAPI
  3. APIfind by (iss, sub)UserTable
  4. UserTablenot foundAPI
  5. Invitationpre-created by e-mailAPI
  6. APIlink if email_verified, else createUserTable
P-7

Permissions as data

Who may see which screen and call which endpoint – the same in frontend and backend.

exo1 · appliedexo2 · appliedexo3 · applied

The solution

  • A catalogue of named permissions, roles that map to them, and assignments in the database.
  • Deny by default: an endpoint without a declared permission is closed.
  • One shared evaluator; the frontend shows and hides with the same permissions.

How it fits together

  1. CataloguepermissionsRoleMap
  2. RoleMaprole -> permissionsGuard
  3. Assignmentsuser x scope -> roleGuard
  4. Guardallow | 403 (deny by default)API
  5. Guardeffective permissionsMeEndpoint
  6. MeEndpoint<Can permission="notes:write">Frontend
P-8

Shared kernel

Backend, frontend and services need the same contracts and rules without re-implementing them.

exo1 · partlyexo2 · partlyexo3 · partly

The solution

  • An innermost kernel without dependencies, holding contracts, permissions and error codes.
  • Server infrastructure in an outer layer that depends on the kernel – never the other way round.
  • The kernel has its own tests and the same check command as its consumers.

How it fits together

  1. ServerInfradepends onKernel
  2. APIdepends onServerInfra
  3. APIdepends onKernel
  4. Webdepends onKernel
  5. Appdepends onKernel
P-9

One check gate

"Done" must mean the same for a developer, an agent and the pipeline.

exo1 · appliedexo2 · appliedexo3 · applied

The solution

  • One command is the definition of done: lint, types, unit and integration tests against a real database.
  • End-to-end tests through the real login before every release.
  • The same command runs locally, in the agents' hooks and in CI.

How it fits together

  1. Developerbefore commitcheck
  2. Agentedit -> fast checks; stop -> run checkHooks
  3. Hookssame commandcheck
  4. CI(cit)on every PR and push to maincheck
  5. Releaseon tag vX.Y.Zcheck
  6. Releasereal login, full stacke2e
  7. Releasedeploy tagged commit, wait for versionPlatform
P-10

The agent layer

Agents need the conventions and a way to check their own work – without a huge context or blanket permissions.

exo1 · appliedexo2 · appliedexo3 · applied

The solution

  • One instruction file per repository, distilled from the architecture, and topic documents read on demand.
  • Skills for the recurring moves, each ending by running the checks.
  • Hooks close the feedback loop, and permissions are scoped.

How it fits together

  1. Blueprintdistilled rulesCLAUDE.md
  2. CLAUDE.mdalways loadedAgent
  3. TopicDocsread on demandAgent
  4. Skillsrecurring moves, end with checksAgent
  5. Agentedit / stopHooks
  6. Hooksfast checks; reminder to run checkChecks
  7. Checksgreen | redAgent

"Applied" means the exo's code contains the pattern. It is only proven once a real application has been built on the exo.

← Back to the factory