Pattern Inheritance: A Fork-Based Strategy for Scaling Service Standards

Sebastián Ramírez (the creator of FastAPI) maintains full-stack-fastapi-template, which provides:

• FastAPI backend with SQLModel + Alembic migrations
• Async SQLAlchemy engine configuration
• JWT-based authentication
• Pydantic settings for config
• Docker Compose for local development
• Pre-built CRUD patterns
• Test infrastructure with pytest

This template represents thousands of hours of community iteration⁴. The async database patterns alone encode subtle decisions about connection pool sizing, session lifecycle management, and transaction isolation that most teams would need months to get right independently.

The Cookiecutter ecosystem offers parameterized project generation. Notable FastAPI templates include:

• cookiecutter-fastapi – Focused on API-only services
• fastapi-project-template – Includes CLI tooling and Makefile-driven workflows

Cookiecutter templates have a key advantage: they're parameterized. You fill in your project name, choose your options, and get a generated scaffold⁵. But they also have a critical limitation that motivates the rest of this post.

When you run cookiecutter or git clone on a template, you get a snapshot. A point-in-time copy of the template's state. From that moment forward, your project and the template are completely disconnected.

graph LR
    subgraph "Clone / Generate (Point-in-Time Snapshot)"
        direction LR
        Template[Community Template<br/>v1.0] -->|clone / generate| TeamRepo[Team's Service]
        Template -->|v1.1: security fix| Nowhere1[❌ Not inherited]
        Template -->|v1.2: perf improvement| Nowhere2[❌ Not inherited]
        Template -->|v1.3: new best practice| Nowhere3[❌ Not inherited]
    end

This means:

• When the community template fixes a security vulnerability in its auth middleware, you don't get the fix.
• When it upgrades to a faster async database driver, you don't get the improvement.
• When it adopts a new best practice for connection pool management, you don't benefit.

Every improvement in the template requires someone on your team to notice it, understand it, and manually port it into your codebase. In practice, this never happens. The template was useful on day one and forgotten by day two.

This is the open source template you've chosen as your foundation. You don't modify it directly. It represents the community's best understanding of how to build this type of service⁹.

This is where your platform team applies organizational opinions on top of the community template. This fork is maintained by your platform or infrastructure team and represents your org's "blessed" way to build a service of this type.

Typical org-level customizations include:

• Authentication: Swap JWT for your org's OIDC provider or service mesh auth.
• Observability: Add your org's OpenTelemetry configuration, custom metrics, and tracing headers.
• Secrets management: Integrate with Vault, AWS Secrets Manager, or whatever your org uses.
• CI/CD: Replace generic GitHub Actions with your org's pipeline templates.
• Deployment manifests: Add Kubernetes manifests, Helm charts, or Terraform modules that match your infrastructure.
• Compliance: Add security scanning, license checking, and audit logging requirements.
• Internal libraries: Wire in your org's shared Python packages for common concerns.

The platform team's job is to keep this fork synchronized with upstream while maintaining the org's customizations. This is the hardest job in the hierarchy, and the one that makes the whole thing work¹⁰.

Individual teams fork the org's gold standard to create their specific services. A team building a payments service forks acme-corp/fastapi-service-template into acme-corp/payments-service, then adds their domain-specific models, routes, and business logic.

Teams get the org's opinions "for free" and can focus entirely on their domain problem. When the platform team pushes an improvement to the gold standard (say, upgrading the OpenTelemetry SDK or fixing a connection pool misconfiguration), teams can pull that change into their fork with a standard git merge.

On GitHub, fork the community template into your org's namespace:

tiangolo/full-stack-fastapi-template → acme-corp/fastapi-service-template

Then clone your org fork locally:

git clone git@github.com:acme-corp/fastapi-service-template.git
cd fastapi-service-template
git remote add upstream git@github.com:tiangolo/full-stack-fastapi-template.git
git remote -v
# origin    git@github.com:acme-corp/fastapi-service-template.git (fetch)
# origin    git@github.com:acme-corp/fastapi-service-template.git (push)
# upstream  git@github.com:tiangolo/full-stack-fastapi-template.git (fetch)
# upstream  git@github.com:tiangolo/full-stack-fastapi-template.git (push)

This is a critical decision¹¹. I recommend maintaining two long-lived branches in the org fork:

• upstream-mirror: Tracks the upstream template exactly. Never commit org changes here.
• main: Contains the org's customizations on top of upstream.

# Create the mirror branch
git checkout -b upstream-mirror
git push origin upstream-mirror

# main branch is where org customizations live
git checkout main

When you want to sync with upstream:

# Update the mirror
git checkout upstream-mirror
git fetch upstream
git merge upstream/main
git push origin upstream-mirror

# Merge upstream changes into org's main
git checkout main
git merge upstream-mirror
# Resolve conflicts, keeping org customizations where intentional
git push origin main

The upstream-mirror branch gives you a clean diff between "what upstream looks like" and "what our org version looks like." This is invaluable for understanding exactly what your org has changed.

For simple, infrequent syncs, GitHub's "Sync fork" button and the gh repo sync CLI command offer lighter-weight alternatives. These work well when the org fork has minimal divergence, but for forks with significant customizations you'll want the mirror-branch workflow above to keep a clear audit trail.

Now apply your org's opinions to main. The single most important rule: keep the diff between your fork and its upstream as small as possible. Every line you change in a file that upstream also changes is a future merge conflict. Before modifying an upstream file, ask: "Can I achieve this by adding a new file instead?" Often you can. A new org_middleware.py that's imported by the entrypoint is better than editing the middleware directly.

Some specific guidelines:

Prefer additive changes over modifications. Adding new files (a deploy/ directory, an internal_libs/ package, a .github/workflows/ci.yml) is low-conflict. Modifying files that upstream also modifies (main.py, requirements.txt, Dockerfile) is high-conflict.

Use configuration layers. Instead of editing settings.py directly, create an org_settings.py that imports and extends the base settings. This isolates your changes from upstream's evolution of the settings module.

Document every divergence. Maintain an ORG_CHANGES.md file that catalogs what you've changed and why. When merge conflicts arise, this document tells you whether the conflict is in code you intentionally modified. A typical manifest looks like:

## Org Customizations

### Authentication (modified: app/core/security.py)
- Replaced JWT auth with OIDC integration via org's identity provider
- Added service-to-service mTLS validation

### Observability (added: app/observability/)
- OpenTelemetry auto-instrumentation with custom span attributes
- Structured logging via [[https://www.structlog.org/en/stable/][structlog]] with org-standard fields

### CI/CD (replaced: .github/workflows/)
- Upstream GitHub Actions replaced with GitLab CI
- Added SAST scanning, container scanning, license compliance

### Database (modified: app/core/db.py)
- Connection pool max_size increased from 10 to 50
- Added read-replica routing for GET endpoints

This document is your merge conflict playbook. When upstream changes app/core/security.py and you get a conflict, you check the manifest: "We intentionally replaced this with OIDC. Ignore upstream's changes to the JWT implementation, but check if they've changed anything else in this file."

Teams fork acme-corp/fastapi-service-template into their service repo (acme-corp/payments-service) and set up remotes the same way:

git clone git@github.com:acme-corp/payments-service.git
cd payments-service
git remote add org-template git@github.com:acme-corp/fastapi-service-template.git

Teams should similarly maintain an org-template-mirror branch and merge into main:

git checkout -b org-template-mirror
git fetch org-template
git merge org-template/main
git push origin org-template-mirror

git checkout main
git merge org-template-mirror

With the hierarchy in place, improvements flow downstream through the fork chain. Here's what different types of changes look like in practice:

graph LR
    subgraph "Change Propagation"
        direction LR
        U[Community<br/>Template] -->|"1. Publishes<br/>security fix"| O[Org Fork]
        O -->|"2. Platform team<br/>validates + merges"| OP[Org Main ✅]
        OP -.->|"3. Teams pull<br/>from org-template"| S1[payments-service ✅]
        OP -.->|"3. Teams pull<br/>from org-template"| S2[inventory-service ✅]
    end

Renames are the most common source of painful merge conflicts. If upstream renames app/core/config.py to app/settings/config.py, and your org fork has modifications to the original app/core/config.py, Git may not detect this as a rename-with-modification¹². Instead, you'll see the old file deleted and a new file created, with your org's changes silently lost.

Mitigation: When merging upstream changes that include renames, always diff the deleted file against the new file manually. Use git diff –find-renames with a low similarity threshold to help Git detect renames:

git merge -X rename-threshold=40 upstream-mirror

Upstream pins sqlalchemy==2.0.30 in their requirements.txt. Your org fork has pinned sqlalchemy==2.0.25 because 2.0.30 has a regression with your custom dialect. Three months later, upstream bumps to sqlalchemy==2.1.0 with breaking API changes.

The danger escalates with lock files (poetry.lock, requirements.txt with hashes). Lock file conflicts are virtually impossible to resolve by hand¹³.

Mitigation:

• Don't modify upstream's dependency files directly. Use a layered approach: requirements-base.txt (from upstream) and requirements-org.txt (your overrides) with -r requirements-base.txt at the top.
• Pin upper bounds on critical dependencies in the org fork's override file, so upstream bumps don't silently pull in breaking versions.
• Automate dependency conflict detection in CI: when the org fork merges upstream, run the full test suite before pushing to main.

The application entrypoint (main.py, app/__init__.py, or wherever the FastAPI app instance is created) is a high-conflict zone. Both upstream and your org fork need to modify this file – upstream to add framework features, your org to wire in custom middleware, startup hooks, and shutdown handlers.

If upstream refactors the startup sequence (e.g., moving from a module-level app = FastAPI() to a factory function create_app()), every downstream fork that has modified the entrypoint will face a complex merge.

Mitigation:

• Use a lifecycle hooks pattern. Define well-known hook functions (on_startup(), on_shutdown(), configure_middleware()) in separate files that the entrypoint imports. Upstream owns the entrypoint; your org owns the hook implementations.
• If upstream doesn't support this pattern, propose it upstream. This is a legitimate contribution that benefits everyone.

Alembic migrations have a linear dependency chain: each migration references the previous one's revision ID¹⁴. If upstream adds migration abc123 and your org fork adds migration def456, both claim to be the "head." Alembic calls this a "multiple heads" situation and refuses to run until you create a merge migration. (This is the same Alembic we chose in the decision table above – a great tool, but one that demands careful coordination across fork tiers.)

At the team fork level, every team has domain-specific migrations that diverge from the org template's migrations, compounding the problem further.

Mitigation:

• The org template should only include infrastructure migrations (user tables, auth tables, audit tables). Domain-specific tables belong in team forks.
• Use Alembic's –branch-label feature to namespace migrations: org/ for org-level, domain/ for team-level.
• Document a clear migration merge procedure and include a CI check that validates migration history.

CI/CD pipelines tend to be heavily customized at every level of the hierarchy. Upstream has generic GitHub Actions. Your org replaces them with GitLab CI. Teams add service-specific test stages.

If upstream restructures their CI (renaming jobs, changing the workflow file layout), the merge into your org fork touches files you've completely replaced.

Mitigation:

• Place CI files in a separate, clearly-namespaced directory. If upstream uses .github/workflows/, put your org's CI in .ci/ or .gitlab/. This eliminates conflicts entirely because you're adding files, not modifying upstream's.
• Alternatively, .gitignore upstream's CI files in your org fork and maintain your own.

Dockerfile, docker-compose.yml, and Kubernetes manifests are modified at every tier. Upstream sets up a basic multi-stage build. Your org adds security scanning layers, internal registry references, and specific base images. Teams add service-specific build arguments and sidecar containers.

Mitigation:

• Use Docker Compose extends or override files: docker-compose.yml (upstream) + docker-compose.org.yml (org overrides) + docker-compose.team.yml (team overrides).
• For Dockerfiles, consider a base image strategy: the org publishes a base image with org-specific layers, and team Dockerfiles use FROM acme-corp/python-service-base:latest instead of modifying the upstream Dockerfile.

If upstream renames the top-level Python package (e.g., app → fastapi_app), every file in every downstream fork that imports from app breaks. This is a cascading failure across the entire hierarchy.

Mitigation:

• This is one case where talking to upstream matters. If you're building an org's infrastructure on top of a template, consider opening an issue or PR that establishes the top-level package name as a stable API.
• If you can't prevent it, maintain a thin compatibility shim (app/__init__.py that re-exports from fastapi_app) in the org fork to give teams time to migrate. Remove the shim after a transition period.

The longer you wait between upstream syncs, the harder they get. If you sync monthly, you're merging a month of upstream changes against a month of org changes. Conflicts that would have been trivial in isolation become tangled messes when batched.

The fix is cadence. Set a regular sync schedule – weekly or biweekly – and treat it like any other maintenance task. Automate the fetch and attempt the merge in CI. If it succeeds cleanly, auto-merge. If it conflicts, create a PR for human review. The key is detecting divergence early, even if you don't resolve it immediately.

graph LR
    subgraph "Sync Cadence"
        direction LR
        W1[Week 1<br/>3 upstream commits<br/>easy merge ✅] --> W2[Week 2<br/>5 upstream commits<br/>easy merge ✅]
        W2 --> W3[Week 3<br/>2 upstream commits<br/>1 conflict ⚠️]
        W3 --> W4[Week 4<br/>4 upstream commits<br/>easy merge ✅]
    end

Compare this to syncing quarterly, where you'd face 14 upstream commits in a single merge with compounding conflicts. Small, frequent merges are always easier than large, infrequent ones.

In my experience, the biggest risk to this whole approach is not technical – it's social¹⁵. Teams fork the org template, build their service, and then never sync again. Six months later, the org template has evolved significantly, but the team's fork is frozen at the version from the day they started.

The fork still "works" in the sense that the service runs. But the team has silently opted out of every security patch, performance improvement, and operational standardization the platform team has shipped since then.

Solutions:

• Automated staleness detection: A weekly CI job that checks each team fork's divergence from the org template and posts a report. "Your fork is 47 commits behind org-template/main. Last synced: 3 months ago."
• Org-wide sync sprints: Quarterly, dedicate a day for all teams to sync their forks. Make it a lightweight, scheduled event rather than an emergency.
• Freshness SLO: Set an organizational policy that team forks must be no more than N weeks behind the org template. Enforce it with a dashboard, not a gate.

A GitHub Action to automate staleness detection looks like this:

# .github/workflows/upstream-sync-check.yml
name: Check Upstream Sync
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am
  workflow_dispatch:

jobs:
  check-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Fetch upstream
        run: |
          git remote add upstream https://github.com/tiangolo/full-stack-fastapi-template.git
          git fetch upstream
      - name: Check divergence
        run: |
          BEHIND=$(git rev-list --count HEAD..upstream/main)
          if [ "$BEHIND" -gt 0 ]; then
            echo "::warning::Org fork is $BEHIND commits behind upstream"
          fi

Run the same pattern on team forks, checking against the org template.

Because the org fork is shared infrastructure for every team, a bad change – a poorly configured middleware, a broken migration, a dependency bump with a subtle regression – can propagate to every service that syncs.

Clear ownership and review processes are essential:

• Dedicated owners: The platform team owns the org fork. Changes require review from at least one platform engineer.
• Change classification: Not every upstream change needs to be merged. The platform team should evaluate each upstream release for relevance and risk.
• Staged rollout: After merging upstream changes, deploy a canary service (a real but low-traffic service) before announcing the update to all teams.
• Changelog: Maintain a changelog in the org fork that translates upstream changes into org-relevant context. "Upstream upgraded SQLAlchemy to 2.1. This changes how async sessions are created. If you've customized session creation, see migration guide."
• Semantic commit prefixes: Prefix commits to distinguish org customizations from upstream merges (e.g., org: add Vault integration vs. upstream: merge tiangolo/full-stack-fastapi-template v0.7.0). When debugging a merge conflict, you immediately know whether the conflicting change is one you own or one you inherited.

For the org-to-team relationship, consider publishing tagged releases of the org fork rather than having teams track main directly. Tagged releases give teams a stable upgrade target (v2.3.0 → v2.4.0) with a changelog, while tracking main risks pulling in half-finished platform work. The trade-off is freshness: teams on tagged releases won't get critical fixes until the next release unless you backport them.

Sometimes a team's service diverges so far from the template that merging org-template updates becomes more work than it's worth. The payments service has rewritten the entire database layer to use event sourcing. The notifications service has replaced FastAPI's routing with a custom message broker integration. At this point, the fork relationship is a liability, not an asset.

This is fine. Not every service needs to stay on the fork. The pattern inheritance approach is most valuable for services that follow the "standard" pattern. When a service has genuinely unique requirements that make it architecturally different from the template, it's better to detach it:

# Remove the org-template remote
git remote remove org-template

# Delete the mirror branch
git branch -D org-template-mirror

To make detachment a normal part of service lifecycle rather than a stigmatized escape hatch, define clear criteria:

• If merging org-template updates has required manual conflict resolution in more than 50% of the last 10 syncs, consider detaching.
• If the service has replaced more than 30% of the template's files with custom implementations, consider detaching.
• If the service's architecture has diverged from the template's assumptions (different database, different auth model, different deployment target), detach.

Explicitly detaching is better than maintaining a fiction of inheritance that creates merge conflicts without delivering value. The fork hierarchy should be opt-in, not mandatory.

A change at any tier can break a downstream fork. Upstream refactors a utility function; the org fork's customization of that utility breaks; every team fork that uses the org's customization breaks.

Ideal testing looks like this:

1. Upstream CI: Tests the template in isolation (community's responsibility).
2. Org fork CI: Tests the template with org customizations applied. This catches incompatibilities between upstream changes and org opinions.
3. Team fork CI: Tests the specific service. This catches incompatibilities between org changes and domain logic.

The critical gap is step 2. If the org fork doesn't have robust CI, broken upstream merges will silently propagate to every team. Invest in the org fork's test suite – it's the immune system for your entire service fleet.

Instead of forks, put all services in a single repository with shared libraries for common patterns:

monorepo/
├── libs/
│   ├── fastapi-common/     # Shared middleware, auth, config
│   ├── db-common/          # SQLAlchemy setup, session management
│   └── observability/      # OpenTelemetry, logging
├── services/
│   ├── payments/
│   ├── inventory/
│   └── notifications/
└── templates/
    └── service-scaffold/   # Cookiecutter for new services

Pros: Atomic changes across services and libraries, no merge conflicts, single CI pipeline, easy refactoring.

Cons: Requires monorepo tooling (Bazel, Pants, Nx)¹⁶, CI complexity scales with repo size, teams lose autonomy over their release cycle, doesn't inherit from community templates.

Best for: Organizations with strong platform teams and existing monorepo infrastructure.

Tools like cruft (built on top of Cookiecutter) solve the "snapshot problem" by tracking which template version was used to generate a project and offering an update mechanism¹⁷:

# Generate project from template
cruft create https://github.com/acme-corp/fastapi-template

# Later, update to latest template version
cruft update

cruft update computes the diff between the template version you generated from and the current version, then applies that diff to your project.

Pros: No Git fork management, works with any Cookiecutter template, clear diffing between template versions.

Cons: Updates are one-way (no pushing changes back to the template), conflicts are handled at the file level (less granular than Git), doesn't compose into a multi-tier hierarchy as naturally.

Best for: Organizations that want template inheritance without the Git overhead.

Platforms like Backstage provide service scaffolding as a feature of a broader developer portal:

• Service catalog with templates
• One-click service creation from "golden path" templates
• Built-in CI/CD integration
• Plugin ecosystem for org-specific features

Pros: Higher-level abstraction, UI-driven, integrates service creation with service management, good for organizations with many non-expert users.

Cons: Heavy infrastructure (Backstage itself is a significant service to maintain)¹⁸, templates are still snapshots (no inheritance), vendor-specific if using a commercial platform.

Best for: Large organizations (500+ engineers) with dedicated platform teams.

Instead of inheriting an entire project template, publish your patterns as installable packages:

# In your service's requirements.txt
acme-fastapi-core==2.3.0    # Auth, middleware, config
acme-db-common==1.5.0        # SQLAlchemy setup, migrations base
acme-observability==3.1.0    # OpenTelemetry, structured logging

Teams install these packages and compose their service from them:

from acme_fastapi_core import create_app, configure_auth
from acme_db_common import get_async_session, Base
from acme_observability import setup_tracing

app = create_app()
configure_auth(app)
setup_tracing(app)

Pros: Versioned dependencies with semantic versioning, teams can pin to specific versions, no merge conflicts, standard package management.

Cons: Requires extracting patterns into well-designed APIs (significant upfront investment), doesn't provide project structure (only runtime patterns), teams still need a scaffold for the "rest" of the project.

Best for: Organizations with mature platform teams that can invest in library design.

The fork hierarchy occupies a sweet spot: low upfront investment, inherits from community work, and scales to a meaningful number of services before the merge overhead becomes a bottleneck. For most mid-sized engineering organizations (50-500 engineers, 5-50 services on a common stack), it's the right starting point¹⁹.

These approaches aren't mutually exclusive. Mature organizations often combine package-based composition for runtime patterns (auth, observability, database utilities) with a fork hierarchy for project structure (directory layout, CI pipelines, deployment manifests, Dockerfile conventions). The fork gives you the scaffold; the packages give you the runtime behavior.