Checklist voor broncode-overdracht voor klanten en bureaus

Wat een broncode-overdracht moet bereiken

Een broncode-overdracht is het moment waarop het project ophoudt ‘iets te zijn dat het bureau kan draaien’ en verandert in ‘iets dat de klant kan bezitten’. Zonder een duidelijke overdracht ontstaan veelvoorkomende problemen snel: de app bouwt alleen op één laptop, productie hangt af van een geheim dat niemand kan vinden, of een kleine update verandert in dagenlang giswerk.

Het doel van elke broncode-overdrachtschecklist is eenvoudig: na de overdracht kan de klant het product bouwen, draaien en deployen zonder dat het bureau standby hoeft te zijn. Dat betekent niet "nooit meer ondersteuning". Het betekent dat de basis herhaalbaar en gedocumenteerd is, zodat de volgende persoon het met vertrouwen kan oppakken.

Wat als deliverables telt, moet expliciet zijn. Minimaal bevat een volledige overdracht doorgaans:

• De volledige repository (inclusief deployment-bestanden en migratiescripts)
• Setup-docs die werken op een schone machine
• Toegangsoverdracht (accounts, permissies en waar het systeem draait)
• Een runbook voor routinetaken (deployen, rollback, backups, logs)
• Een definitieve “known-good” versietag of snapshot waar de klant naar kan verwijzen

Scope is net zo belangrijk als inhoud. Sommige overdrachten dekken maar één omgeving (bijvoorbeeld productie). Andere omvatten dev, staging en productie met aparte instellingen en processen. Als je niet noemt welke omgevingen zijn inbegrepen, gaat iedereen uit van iets anders, en daar ontstaan storingen.

Een praktische manier om succes te definiëren is een verificatietest: een persoon die de app niet heeft gebouwd kan de code exporteren (bijvoorbeeld vanaf een platform zoals Koder.ai), de docs volgen, omgevingsvariabelen instellen, migraties draaien, bouwen en deployen naar de afgesproken omgeving.

Deze checklist richt zich op technische gereedheid: omgevingsvariabelen, secrets-rotatie, database-migraties, deployment-scripts en build-verificatie. Het behandelt geen juridische voorwaarden, contracten, IP-clausules of betalingsgeschillen. Die zaken zijn ook belangrijk, maar horen thuis in een apart akkoord.

Voordat je exporteert: stem eigenaarschap en timing af

Een schone overdracht begint vóórdat er geëxporteerd wordt. Als je afspreekt wie wat bezit en wanneer, voorkom je last-minute verrassingen zoals kapotte deploys, onbetaalde hosting of ontbrekende toegang.

Stel de overdrachtsdatum en een korte freeze-window vast

Kies een overdrachtsdatum en definieer een freeze-window (vaak 24–72 uur) waarin alleen urgente fixes worden doorgevoerd. Dit houdt de geëxporteerde code en het draaiende systeem in sync. Als er tijdens de freeze een hotfix nodig is, noteer precies wat er is veranderd en zorg dat het in de definitieve export wordt opgenomen.

Maak eigendom van accounts en betalingen duidelijk

Bepaal wie DNS, cloud-hosting en eventuele betaalde diensten na de overdracht bezit. Dit is niet alleen papierwerk. Als de betalingen op de kaart van het bureau blijven staan, kunnen services later zonder waarschuwing gepauzeerd worden.

Een snelle manier om het concreet te maken:

• Noem de account-eigenaar voor DNS, hosting en e-mail
• Bevestig wie elke rekening betaalt vanaf de overdrachtsdatum
• Beslis of accounts worden overgedragen of opnieuw worden aangemaakt onder de klant
• Leg het supportcontact per provider vast

Schrijf dit in eenvoudige taal zodat beide partijen het kunnen volgen.

Noem de omgevingen en waar ze draaien

Kom overeen welke omgevingen bestaan (local, staging, production) en waar elke omgeving draait. Noteer of staging een aparte server is, een aparte database, of slechts een feature-flag. Als je een platform zoals Koder.ai hebt gebruikt, bevestig dan wat daar gehost is versus wat na export in de infrastructuur van de klant zou moeten draaien.

Verzamel toegang vroeg

Wacht niet tot de laatste dag om toegang te vragen. Zorg dat de juiste mensen bij de benodigde plekken kunnen: de repo, CI, hosting, de database en de e-mailprovider.

Stem ook het finale acceptatietest- en sign-off-proces af. Bijvoorbeeld: “De klant kan bouwen vanaf een schone machine, migraties draaien, deployen naar staging en de smoke-test doorstaan. Daarna tekenen beide partijen schriftelijk af.”

Repo- en documentatiebasis die je moet opnemen

Een goede broncode-overdrachtschecklist begint met een repo die een nieuw team binnen enkele minuten kan openen en begrijpen. Bevestig wat inbegrepen is (app-code, config-templates, scripts) en wat opzettelijk ontbreekt (echte secrets, private keys, grote gegenereerde bestanden). Als iets is uitgesloten, zeg dan waar het staat en wie het bezit.

Houd de structuur voorspelbaar. Streef naar duidelijke top-level mappen zoals frontend/, backend/, mobile/, infra/, scripts/ en docs/. Als het project een monorepo is, leg dan uit hoe de onderdelen zich verhouden en hoe je elk onderdeel runt.

Je README moet bruikbaar zijn voor iemand die het project niet heeft gebouwd. Het moet prerequisites en het snelste pad naar een werkende dev-run dekken, zonder giswerk.

Wat minimaal te documenteren

Voeg een korte, menselijke README-sectie toe die de volgende vragen beantwoordt:

• Wat deze repo bevat en wat het doet (één alinea)
• Prerequisites met exacte versies (runtime, package manager, Docker indien nodig)
• Eén-commando startstappen voor lokale ontwikkeling (en wat “succes” eruitziet)
• Hoe tests te draaien en een productie-artifact te bouwen
• Waar key docs te vinden zijn: architectuurnotities, migraties, deployment-notities

Voeg eenvoudige architectuurnotities toe in duidelijke taal: wat praat met wat, en waarom. Een klein diagram is optioneel, maar een paar zinnen zijn meestal genoeg. Voorbeeld: “React-frontend roept de Go-API aan. De API leest en schrijft naar PostgreSQL. Background jobs draaien als een aparte worker-process.”

Tot slot: includeer een versieerde changelog of releasenotes voor de overdrachtbuild. Dit kan een CHANGELOG.md zijn of een kort "handoff release notes"-bestand dat de exacte commit/tag vermeldt, wat er is opgeleverd en bekende issues.

Als de code is geëxporteerd vanaf een platform zoals Koder.ai, vermeld dan het gegenereerde projecttype (web, server, mobiel), de verwachte toolchain (bijvoorbeeld React, Go, PostgreSQL, Flutter) en de ondersteunde OS/tooling-versies die de klant moet gebruiken om de build te reproduceren.

Omgevingsvariabelen: inventaris en documentatie

Omgevingsvariabelen zijn vaak de reden dat een “werkende app” faalt direct na overdracht. Een goede checklist behandelt ze als onderdeel van het product, niet als bijzaak.

Begin met het schrijven van een inventaris die een nieuw team kan volgen zonder te gokken. Houd het in klare taal en geef een voorbeeld van het formaat van waarden (geen echte secrets). Als een variabele optioneel is, vermeld wat er gebeurt als deze ontbreekt en welke default wordt gebruikt.

Een eenvoudige manier om de inventaris te presenteren is:

• Variabele naam, wat het regelt en een voorbeeldformaat
• Verplicht vs optioneel, plus eventueel standaardgedrag
• Waar het wordt ingesteld (CI, hosting dashboard, lokale .env-file)
• Welke omgevingen verschillende waarden nodig hebben (dev, staging, production)
• Wie wijzigingen bezit (klant, bureau of gedeeld)

Markeer omgeving-specifieke verschillen duidelijk. Bijvoorbeeld: staging kan wijzen naar een testdatabase en een sandbox-betaalprovider, terwijl productie live diensten gebruikt. Noteer ook waarden die overeen moeten komen tussen systemen, zoals callback-URL's, allowed origins of mobile app bundle identifiers.

Documenteer waar elke waarde nu staat. Veel teams verspreiden waarden over plekken: lokale .env-bestanden voor ontwikkeling, CI-variabelen voor builds en hosting-instellingen voor runtime. Als je Koder.ai hebt gebruikt om de app te exporteren, voeg dan een .env.example toe en een korte notitie over welke variabelen ingevuld moeten worden vóór de eerste build.

Tot slot: bewijs dat er geen secrets in de repo verborgen zitten. Controleer niet alleen de huidige bestanden. Bekijk de commit-geschiedenis op per ongeluk geüploade sleutels, oude .env-bestanden of gekopieerde credentials in sample-configs.

Concreet voorbeeld: een React-frontend plus een Go-API kan API_BASE_URL nodig hebben voor de webapp, en DATABASE_URL plus JWT_SIGNING_KEY voor de backend. Als staging een andere domeinnaam gebruikt, noteer beide waarden en waar je ze moet wijzigen, zodat het nieuwe team niet per ongeluk staging-instellingen naar productie pusht.

Secrets-rotatie: veilig overdragen en bewijs leveren dat het werkt

Een overdracht is pas compleet als de klant elke credential controleert die de app nodig heeft. Dat betekent secrets roteren, niet alleen delen. Als een bureau (of een ex-contractor) nog werkende sleutels heeft, laat je een open deur die je niet kunt auditen.

Begin met een volledige inventaris. Stop niet bij database-wachtwoorden. Neem derdepartij-API-keys, OAuth-clientsecrets, webhook signing secrets, JWT-signing keys, SMTP-credentials, opslagtoegangssleutels en alle “tijdelijke” tokens in CI mee.

Hier is een eenvoudige checklist voor rotatiedag:

• Noem elk secret, wat het ontgrendelt en waar het momenteel is ingesteld (lokale env-bestanden, CI, hosting dashboard, vault)
• Maak nieuwe credentials aan onder de accounts van de klant en stel een eigenaar in voor elk (een persoon en een team-inbox)
• Update de app-config om de nieuwe waarden te gebruiken en deploy eerst naar een staging- of testomgeving
• Intrek de oude credentials direct nadat de nieuwe bevestigd werkend zijn
• Schrijf de exacte rotatiestappen op zodat de volgende rotatie saai en snel is

Na rotatie: bewijs dat er niets is stukgegaan. Voer snelle “real user”-tests uit in plaats van alleen logs te checken.

Focus op flows die van secrets afhangen:

• Inloggen, registratie, wachtwoordreset en token-refresh
• Betalingen, e-mailverzending en bestandsuploads
• Webhooks (signature-verificatie en retry-handling)
• Background jobs of geplande taken die externe API's aanroepen
• Admin-acties die bevoegde endpoints raken

Voorbeeld: als je een project exporteerde van Koder.ai en de app gebruikt een betaalprovider plus e-mailleverancier, roteer dan beide sleutels, redeploy, voer een kleine testtransactie uit en verstuur een testmail. Pas nadat die slagen, intrek je de door het bureau beheerde sleutels.

Documenteer ten slotte waar secrets voortaan leven (vault, CI-variabelen of hosting-instellingen), wie ze kan wijzigen en hoe veilig terug te draaien als een rotatie fouten veroorzaakt.

Database-migraties en dataverwerking

Een overdracht kan er “klaar” uitzien terwijl de database als eerste stuk gaat. Behandel migraties en data als een product op zich: versioned, herhaalbaar en getest.

Begin met het noteren van de huidige databaseversie en waar migraties in de repo staan. Wees specifiek: de folderpad, naamgevingspatroon en de laatste migration-ID (of timestamp). Als je PostgreSQL gebruikt (veelvoorkomend met Go-backends), noteer dan ook vereiste extensies.

Wat te documenteren (zodat iemand anders het kan draaien)

Voeg een kort runbook toe dat de volgende vragen beantwoordt:

• Welke command uitvoert migraties en in welke volgorde dingen moeten lopen (create database, apply migrations, dan seeds)
• Hoe het per omgeving verschilt (local, staging, production), inclusief eventuele “safe mode”-flags
• Of migraties automatisch bij deploy worden uitgevoerd of handmatig moeten worden gerund, en wie daartoe bevoegd is
• Seed-data strategie: geen, demo-only, of minimale vereiste records (admin-gebruiker, standaardinstellingen)
• Rollback-plan: wat omkeerbaar is en wat niet (bijvoorbeeld destructieve column drops)

Rollback verdient eerlijkheid. Sommige wijzigingen zijn alleen te herstellen met een backup-restore. Benoem dat in duidelijke taal en koppel het aan een backupstap (snapshot vóór deploy, verifieer restore-proces).

Draai vóór afronding van de overdracht migraties op een kopie van productiedata als dat mogelijk is. Dit vangt trage queries, ontbrekende indexen en “werkt op lege data”-issues. Een realistische test is: code exporteren, omgevingsvariabelen instellen, een geanonimiseerde dump terugzetten en daarna migraties vanaf nul toepassen. Die enkele oefening valideert een groot deel van elke checklist.

Als de app is gebouwd op een platform zoals Koder.ai en daarna geëxporteerd, controleer dan dubbel of migratiebestanden en eventuele seed-scripts in de export zitten en nog correct door de backend-startprocedure worden aangeroepen.

Build en CI: maak het herhaalbaar

Een overdracht is pas compleet wanneer iemand anders de app vanaf nul kan herbouwen op een schone machine. Je checklist moet de exacte build-commando's, vereiste versies en de verwachte output bevatten (bijvoorbeeld: “web bundle in /dist”, “API-binary naam”, “Flutter APK-locatie”).

Schrijf de tools en package managers op die je daadwerkelijk gebruikt, niet wat je denkt dat je gebruikt. Voor een typische stack kan dit Node.js (en npm of pnpm) voor een React-webapp, de Go-toolchain voor de server, PostgreSQL-clienttools voor lokale setup en de Flutter SDK voor mobiel zijn.

Maak dependency-installaties voorspelbaar. Bevestig dat lockfiles zijn gecommit (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) en voer een verse installatie uit op een nieuwe computer of clean container om te bewijzen dat het werkt.

Leg vast wat CI doet, stap voor stap, zodat het naar een andere CI-provider gekopieerd kan worden indien nodig:

• Installeer dependencies (met lockfiles)
• Run tests en lint-checks
• Build-outputs (web bundle, server binary, mobile build)
• Produceer artifacts (zip, Docker-image, release bundle)
• Bewaar logs en build-metadata (versie, commit, datum)

Scheid build-time config van runtime-config. Build-time config verandert wat wordt gecompileerd (zoals een API-base-URL die in een webbundle wordt gebakken). Runtime-config wordt geïnjecteerd bij het starten van de app (zoals database-URL's, API-keys en feature flags). Het mengen van deze twee is een veelvoorkomende reden dat “het werkt op CI” maar faalt na deployment.

Voorzie een eenvoudige lokale verificatie-recept. Zelfs een korte set commando's is genoeg:

# Web
pnpm install
pnpm test
pnpm build

# API
go test ./...
go build ./cmd/server

# Mobile
flutter pub get
flutter test
flutter build apk

Als je exporteert vanaf een platform zoals Koder.ai, voeg dan gegenereerde CI-bestanden of build-presets toe die tijdens deployment werden gebruikt zodat de klant dezelfde build buiten het platform kan reproduceren.

Deployment-scripts en releaseproces

Een goede checklist stopt niet bij “hier is de repo.” Ze legt ook uit hoe de app van broncode naar een draaiende service komt, en wie op de knop drukt.

Begin met het opschrijven hoe deploys vandaag plaatsvinden: volledig handmatig (iemand voert commando's op een server uit), CI-gedreven (een pipeline bouwt en deployt) of via een hosted platform. Vermeld waar configs leven en welke omgevingen bestaan (dev, staging, production).

Maak de releasestappen herhaalbaar. Als het proces afhankelijk is van iemand die zich 12 commando's herinnert, zet die dan in scripts en noteer de benodigde permissies.

Wat mee te geven in het deployment-pakket

Geef de klant genoeg om op dag één te deployen:

• Build- en run-commando's (en exacte versies van Node, Go, Flutter, etc.)
• Deployment-scripts (shell-scripts, Makefile-targets of pipeline-configs)
• Vereiste toegang: cloud account-rollen, container registry, DNS, database-admin
• Omgevingssetup-notities: waar env-vars worden gezet en hoe ze per omgeving verschillen
• Release-naming: tags/releases en hoe te identificeren wat draait

Stem downtimeverwachtingen af. Als “zero downtime” vereist is, leg uit wat dat in de praktijk betekent (blue-green, rolling deploy, read-only venster voor migraties). Als downtime acceptabel is, definieer dan een duidelijk venster.

Statische assets en caches zijn veelvoorkomende pijnpunten. Noteer hoe assets worden gebouwd en geserveerd, wanneer caches gebusted moeten worden en of er een CDN bij betrokken is.

Rollback die je daadwerkelijk kunt uitvoeren

Een rollback moet een kort, getest recept zijn gekoppeld aan een tag of release-ID. Bijvoorbeeld: deploy de vorige tag, restore de vorige database-snapshot indien nodig en invalideer caches.

Als de app is gemaakt op Koder.ai en daarna geëxporteerd, vermeld dan de laatst bekende goede snapshot en de exacte exportversie zodat de klant code snel aan een werkende release kan koppelen.

Stappenplan: verifieer de build na export

Verificatie is het moment waarop je leert of de overdracht echt is. Het doel is simpel: iemand nieuw kan de geëxporteerde code nemen, instellen en dezelfde app laten draaien zonder giswerk.

Voordat je begint, noteer wat “correct” eruitziet: de versie van de draaiende app, de huidige commit/tag (als je die hebt) en één of twee belangrijke schermen of API-responses om mee te vergelijken. Als de export van een platform zoals Koder.ai komt, noteer dan de snapshot- of exporttimestamp zodat je kunt bewijzen dat je de laatste staat hebt getest.

1. Bevestig dat de export overeenkomt met productie: controleer de commitgeschiedenis, releasenotes of build-metadata. Vergelijk een zichtbare versiestring of klein gedrag (zoals een specifieke instelling of UI-label) met de draaiende app.
2. Stel omgevingsvariabelen en secrets in: maak de target-omgevingconfig aan (local en staging). Gebruik de geleverde env-var-inventaris en zorg dat niets hardgecodeerd in de repo staat.
3. Installeer dependencies en voer tests uit: doe een schone installatie (geen gecachete node_modules/vendor-folders). Run unittests en eventuele lint-checks precies zoals gedocumenteerd.
4. Draai migraties en start lokaal: zet de database op, pas migraties in volgorde toe en start de app. Bevestig dat de app basisdata kan lezen/schrijven en dat er geen openstaande migraties zijn.
5. Deploy naar staging, voer smoke tests uit en promote: deploy met dezelfde scripts/pipeline die je ook in productie gaat gebruiken. Promote pas als staging aan de verwachtingen voldoet.

Voor smoke tests: houd het kort en gebonden aan risico:

• In- en uitloggen (of een testgebruiker aanmaken)
• Eén kernworkflow end-to-end (aanmaken-bewerken-opslag)
• Eén e-mail/webhook/betalingscallback indien van toepassing
• Basis error handling (foute input, ontbrekend record)
• Logs tonen geen herhaalde crashes of secret-gerelateerde fouten

Als iets faalt: leg het exacte commando, foutoutput en de gebruikte env-vars vast. Die details besparen uren wanneer eigendom verandert.

Veelvoorkomende overdrachtsfouten en hoe ze te vermijden

De snelste manier om een overdracht in een brandbrief te veranderen is aannemen dat “de code genoeg is.” Een goede checklist richt zich op de kleine, saaie details die bepalen of de klant de app daadwerkelijk kan draaien en veranderen zonder jou.

De fouten die de meeste hoofdpijn veroorzaken

De meeste problemen vallen in een paar patronen:

• Secrets zijn niet geroteerd, dus oude agency-wachtwoorden, API-keys of cloud-tokens werken nog na overdracht.
• Omgevingsvariabelen zijn incompleet omdat sommige waarden alleen in CI-instellingen of een hostingdashboard leven, niet in de repo.
• Eenmalige productieaanpassingen worden vergeten, zoals een snelle hotfix, een handmatige DB-aanpassing of een config-toggle direct op de server.
• Database-migraties werken lokaal maar falen in productie vanwege ontbrekende permissies, extensies of schema-eigendom.
• Er is geen rollback-plan en er is geen getagde release (of releasenote) om naar terug te keren als de eerste deploy misgaat.

Hoe ze te voorkomen (zonder weken toe te voegen)

Maak rotatie en toegangsschoonmaak een geplande taak, geen "wanneer we tijd hebben"-item. Stel een datum waarop agency-accounts worden verwijderd, service-keys worden vernieuwd en de klant bevestigt dat ze met hun eigen credentials kunnen deployen.

Voor env-vars: doe een eenvoudige inventaris vanuit drie plekken: de repo, het CI-systeem en de hosting-UI. Valideer het door een schone build te draaien op een verse machine of container.

Voor migraties: test met dezelfde databaseroel die de productie-deploy zal gebruiken. Als productie verhoogde stappen vereist (zoals het inschakelen van een extensie), schrijf die op en maak eigenaarschap duidelijk.

Een realistisch voorbeeld: na het exporteren van een project uit Koder.ai deployt de klant succesvol, maar background jobs falen omdat één queue-URL alleen in het hostingdashboard was gezet. Een simpele env-var-audit had het gevangen. Koppel dat aan een getagde release en een gedocumenteerde rollback (bijvoorbeeld “redeploy tag v1.8.2 en restore de laatste snapshot”) en het team vermijdt downtime.

Eindchecklist, een eenvoudig voorbeeld en vervolgstappen

Als je maar één pagina uit deze checklist bewaart, bewaar deze. Het doel is simpel: een schone clone moet draaien op een nieuwe machine, met nieuwe secrets en een database die veilig vooruit kan.

Snelle checks (voer deze uit vanaf een verse clone)

Voer deze checks uit op een laptop die het project nog nooit heeft gezien (of in een clean container/VM). Dat is de snelste manier om missende bestanden, verborgen aannames en oude credentials te vinden.

• Bouw vanaf nul: installeer deps, run tests (indien aanwezig) en produceer een release-build zonder handmatige aanpassingen.
• Config werkt: zet de gedocumenteerde omgevingsvariabelen en bevestig dat de app opstart met een verse configfile of env-setup.
• Secrets zijn geroteerd: verifieer dat de app draait met de nieuwe sleutels, intrek daarna de oude en bevestig dat niets stukgaat.
• Migraties draaien schoon: begin met een lege database, draai migraties en start de app vervolgens om één basisflow te testen.
• Deploymentpad is echt: voer het deployment-script of CI-workflow één keer uit en bevestig dat het dezelfde output produceert.

Een eenvoudig overdrachtexample

Een bureau draagt een React-frontend, een Go-API en een PostgreSQL-database over. Het klantteam clonet de repo, kopieert de meegeleverde .env.example naar echte env-vars en maakt splinternieuwe credentials aan voor de database, e-mailprovider en derdepartij-API's. Ze runnen go test (of het afgesproken testcommando), bouwen de React-app, passen migraties toe op een verse Postgres-instantie en starten beide services. Tot slot deployen ze met het gedocumenteerde script en bevestigen dat dezelfde commit later opnieuw gebouwd kan worden.

Vervolgstappen

Houd de overdracht kort en met eigenaar. Een walkthrough van 30–60 minuten werkt vaak beter dan een lang document.

• Plan een walkthrough en leg beslissingen vast (wie deployt, wie beheert secrets en database-wijzigingen).
• Wijs één eigenaar aan voor productie-toegang en één backup.
• Spreek een finale “acceptance build” commit-hash af en tag deze.
• Als je in Koder.ai hebt gebouwd: exporteer de broncode, gebruik snapshots en rollback tijdens de eerste klantgestuurde deployment om risico te verminderen.