Codebase Onboarding Path: Django Payments Service Handover 1. CODEBASE ASSESSMENT Platform — Python 3.11 / Django 4.2 / DRF monolith with Celery + Redis async workers and Postgres 14. Payments logic isolated in the payments/ app; Stripe is the external dependency of record. Complexity — High. Not because the codebase is large, but because it sits in the payment path with a custom idempotency layer replacing framework primitives — meaning your Django instincts (once you build them) will be actively wrong in the one module that matters most. Documentation State — Effectively absent. No mentor, no author, 4 months of drift. The hand-edited migrations are the only record of certain schema decisions, and they are an unreliable one. Biggest Risk — payments/idempotency.py as a custom replacement for Django transaction decorators. This outranks the 28% coverage because low coverage is a known unknown — you can see the gap and route around it. A custom idempotency layer is an unknown unknown: it looks like ordinary code, it silently changes the semantics of every write path that touches it, and the one person who understood its invariants left. Duplicate charges are the failure mode, and they are irreversible in a way test gaps are not. Secondary risk: split secret management across settings/prod.py and env vars means you cannot trust either source as authoritative during local setup. Safety Priority — Before touching any business logic, you must be able to (a) read payments/idempotency.py and state its invariants aloud, (b) run the full pytest suite locally and know which 72% is unguarded, and (c) confirm which secrets resolve from where. No write path is touched until all three hold. 2. ONBOARDING PATH Your 6 years of backend Python means environment setup, Python idioms, and general service architecture are compressed to a single day — you don't need hand-holding on virtualenvs or request lifecycles. What is non-negotiable regardless of seniority is the Django ORM's implicit transaction semantics, the Celery execution model, and the idempotency module's invariants: FastAPI experience actively mispredicts all three, and payments code punishes mispredictions permanently. Week 1: Read-Only Orientation Day 1 — Environment and boundary mapping Setup: Clone, pyenv + poetry install (or pip-tools, per repo lockfile). Bring up Postgres 14 and Redis via docker-compose.yml (or equivalent). Confirm pytest runs green before changing anything. Files to read: settings/base.py, settings/prod.py, settings/local.py (or equivalent), pyproject.toml, .github/workflows/lint.yml (or equivalent). Concept: Django settings resolution order and how DJANGO_SETTINGS_MODULE selects it. Note every secret read from settings/prod.py versus os.environ — write the split down. Hands-on: Produce a two-column list: secrets in code vs secrets in env. Do not fix anything. Milestone: "You can boot the service locally and name every configuration value whose production source differs from your local source." Day 2 — Django ORM as a FastAPI refugee Setup: python manage.py shell_plus if django-extensions is present; otherwise manage.py shell. Files to read: payments/models.py, payments/migrations/ — specifically the three hand-edited files. Concept: Django's implicit-transaction-per-request model versus explicit session handling in SQLAlchemy/FastAPI. select_for_update, atomic() nesting, and why save() is not INSERT. Then: what a hand-edited migration means — the schema and the migration history may disagree. Hands-on: Diff live schema against migration state: python manage.py makemigrations --check --dry-run. Record any drift. Milestone: "You can state, for each hand-edited migration, whether the database matches what Django believes it applied." Day 3 — The idempotency layer Setup: None; read-only day. Files to read: payments/idempotency.py, then every call site (rg "idempotency" payments/). Concept: What guarantee this module claims, what it actually enforces, and where it diverges from transaction.atomic. Identify its silent-failure paths — cases where it returns without raising. Hands-on: Write a one-page memo: invariants, assumptions, and the three ways you believe it can be violated. This memo is your first review artifact. Milestone: "You can explain, without reading the file, what happens when the same Stripe event ID arrives twice — and what happens when it arrives twice concurrently." Day 4 — Webhook ingress path Setup: Stripe CLI (stripe listen --forward-to localhost:8000/...) against test-mode keys only. Files to read: payments/webhooks.py *(or equivalent)*, payments/urls.py, payments/serializers.py. Concept: Signature verification, event dispatch, and where the handler hands off to Celery versus completing inline. Hands-on: Replay three existing event types through the CLI. Trace each end-to-end with logging. Milestone: "You can trace a Stripe event from HTTP ingress to final DB write, naming every module it passes through." Day 5 — Celery execution model Setup: Run a worker locally: celery -A <project> worker -l info. Files to read: payments/tasks.py, celery.py (or equivalent), Redis broker config in settings/base.py. Concept: At-least-once delivery, retry semantics, and why a retried task and the idempotency module must agree. This is where duplicate charges originate. Hands-on: Force a task failure and observe retry behaviour. Confirm whether retries re-enter the idempotency guard. Milestone: "You can describe what a Celery retry does to a half-completed payment write, and whether the current code survives it." Week 2: Guarded Contribution Day 6 — Test coverage cartography Hands-on: Run pytest --cov=payments --cov-report=html. Identify which of the money-movement paths are unguarded. Add characterization tests for the two highest-traffic webhook handlers — tests that assert current behaviour, not desired behaviour. Milestone: "You can point to the specific uncovered lines in payments/ that a bad deploy would silently break." Day 7 — Fix the CI gap Hands-on: Extend .github/workflows/ to run pytest on PR, not just lint. Add --cov-fail-under at current measured coverage as a ratchet floor. Milestone: "By end of Day 7, no PR can merge that lowers coverage below today's baseline." Day 8 — First non-payment change Hands-on: Ship something read-only: a new admin view, a logging improvement, or a serializer field addition. Full PR cycle including staff-engineer review. Milestone: "You have merged and deployed a change through the real pipeline, and know how long it takes to reach production." Day 9–10 — Handler scaffolding Hands-on: Build the new webhook event handler behind a feature flag, wired to a no-op. Write its tests first. Do not enable it. Milestone: "By end of Day 10, your handler exists, is tested, is deployed, and does nothing in production." Week 3: Independent Delivery Day 11–13 — Handler implementation Hands-on: Implement handler logic, routed through payments/idempotency.py exactly as existing handlers do. Deviating from the established pattern here is the single most dangerous thing you could do this month. Milestone: "Your handler processes real test-mode events correctly, including a deliberate duplicate delivery." Day 14–15 — Rollout Hands-on: Enable in staging, then production behind the flag at 100%. Monitor for one full deploy cycle. Write the runbook entry. Milestone: "By end of Day 15, your feature is live, you wrote the doc that didn't exist for you, and you know how to roll it back." 3. CONCEPT MASTERY CHECKLIST # Concept Verification Method Priority 1 Idempotency module invariants Explain duplicate-event behaviour from memory to the staff engineer; they confirm Must 2 Celery retry × payment write interaction Force a mid-task failure locally, predict the DB state before checking Must 3 Django implicit transactions Correctly predict whether a given code block commits partially, before running it Must 4 Secret resolution split Produce the two-column secrets list; staff engineer finds no missing entries Must 5 Migration/schema drift Run makemigrations --check and explain each reported difference Must 6 Stripe signature verification Send a deliberately malformed signature and predict the exact rejection path Should 7 Webhook → task handoff boundary Draw the boundary from memory; matches payments/webhooks.py Should 8 Coverage topology of payments/ Name the three riskiest uncovered functions without opening the report Should 9 Deploy and rollback mechanics Execute a rollback in staging unaided Should 10 DRF serializer validation order Add a field with cross-field validation and predict error shape Nice 4. CRITICAL FILE MAP Category File Path Why It Matters When to Read Core risk payments/idempotency.py Custom replacement for framework transaction handling; source of duplicate-charge risk Day 3, before anything else Ingress payments/webhooks.py (or equivalent) Entry point for all Stripe events; signature verification lives here Day 4 Async payments/tasks.py Celery tasks that complete money movement; retry semantics apply Day 5 Data payments/models.py Schema of record for payment state Day 2 Data payments/migrations/ Three hand-edited files; migration history may not match live schema Day 2 Config settings/prod.py Contains secrets that should be in env; authoritative for prod behaviour Day 1 Config settings/base.py Celery broker, DB, and shared settings Day 1 Async infra celery.py (or equivalent) App wiring, queue routing, retry defaults Day 5 CI .github/workflows/lint.yml (or equivalent) Only automated gate that currently exists Day 1, extend Day 7 Local infra docker-compose.yml (or equivalent) Postgres 14 + Redis for local dev Day 1 5. KNOWN LANDMINES Landmine Location Why It's Dangerous How to Navigate Custom idempotency layer payments/idempotency.py Overrides Django transaction semantics; silent-failure paths return without raising Never bypass it; mirror existing call-site patterns exactly 28% test coverage payments/ broadly Money-movement paths largely unguarded; regressions ship silently Add characterization tests before any edit; ratchet floor in CI Hand-edited migrations payments/migrations/ (3 files) Django's migration state may not match live schema Run makemigrations --check before every schema change Secrets split code/env settings/prod.py + env Local and prod resolve differently; a "working" local test proves little Maintain the two-column map; treat prod as authoritative CI runs lint only .github/workflows/ Nothing stops a failing-test merge Add pytest to PR workflow on Day 7 Celery at-least-once delivery payments/tasks.py Retries can re-execute partial writes Verify every task is idempotency-guarded before modifying it No original author Whole repo No one can confirm intent behind non-obvious code Write memos as you go; they become the missing docs 6. MENTOR CHECKPOINTS No dedicated mentor is available and the original author left four months ago. These are outside-review points using the staff engineer's two weekly 30-minute slots — treat them as scarce and come with written artifacts, not open-ended questions. Day Checkpoint What to Review 3 Idempotency memo review Your one-page invariants memo; staff engineer corrects misreadings 5 Retry-safety review Your account of Celery retry × payment write interaction 7 CI change PR Coverage ratchet threshold and workflow config 10 Flagged handler PR Scaffolding, tests, and flag wiring before any logic lands 13 Implementation PR Handler logic and idempotency call-site conformance 15 Rollout retro (self) Runbook entry you wrote; log it as the doc that should have existed I'd defend spending all of Day 3 on payments/idempotency.py before writing a single line of code over any competing use of that day. The obvious alternative — start contributing early to build momentum — is right for most handovers and wrong for this one. A custom replacement for a framework primitive is the highest-entropy artifact in any codebase: it encodes decisions no documentation captured, made by someone unreachable, in the one module where being wrong costs real money and cannot be rolled back. Test coverage you can add later; a misunderstanding of that module compounds into every subsequent change you make. Read it first, or spend three weeks building on a foundation you have merely assumed.