A common story: a business pays for a custom system, it works well for a year or two, then the freelancer moves abroad or the agency closes. Something breaks. Nobody has the server password, the code is on the developer’s personal account, and a new team spends weeks just figuring out how the system is deployed. The business owned the software on paper but not in practice.
A proper handover prevents this. It should be written into the contract and checked item by item before the final payment. Here is what to ask for.
1. Source code in a repository you control
- All code in a Git repository owned by your company account, not the developer’s personal account.
- Full commit history, not a zip file of the final version.
- Every component included: backend, frontend, mobile apps, admin panels, scripts and infrastructure configuration.
- Confirmation that the repository builds successfully from scratch.
Ideally code lives in your repository throughout the project, not only at the end. See the software contract checklist.
2. Access and credentials inventory
A secure list, stored in a password manager rather than a document, covering every account the system depends on:
- Hosting, cloud accounts and servers.
- Domain registrar and DNS.
- Database access.
- Email sending, SMS and WhatsApp providers.
- Payment gateways and bank integrations.
- App store developer accounts for Android and iOS.
- Third party APIs, maps, analytics and monitoring services.
- SSL certificates and renewal details.
Each should be registered in your company’s name, with the developer’s access removed or reduced after handover.
3. Architecture overview
A short document, with a diagram, explaining the main parts of the system and how they connect: which services exist, where they run, how data flows, and which external systems are integrated. It does not need to be long. It needs to let a new developer understand the system in an afternoon.
4. Setup and deployment guide
- How to run the project on a developer’s computer.
- Required software versions and environment variables, with example values, not real secrets.
- How to deploy to production step by step, or how the automated pipeline works.
- How to roll back a bad deployment.
Test this by having someone other than the original developer follow it.
5. Database documentation
- Main tables and what they represent.
- Important relationships and business rules enforced in the database.
- How migrations are run.
- Backup schedule, where backups are stored, and how to restore one, tested at least once.
6. Integrations and business logic notes
Every integration hides details that are painful to rediscover: how payment confirmations are verified, how tax is calculated, what happens when the courier API is down. Short notes on these rules save enormous time. See what breaks in API integrations.
7. API documentation
If the system has APIs used by mobile apps or partners, document endpoints, authentication and example requests. Many frameworks can generate this automatically.
8. User and admin guides
Non technical documentation for your staff: how to perform common tasks, manage users, run reports and handle frequent issues. Short screen recordings work very well.
9. Known issues and technical debt
An honest list of known bugs, limitations, shortcuts taken and recommended improvements. A good developer provides this willingly. It tells the next team where to be careful.
10. Licences and third party components
A list of paid licences, subscriptions with renewal dates and costs, and open source libraries used, so nothing expires unnoticed.
11. Monitoring and maintenance notes
- What is monitored and where alerts go.
- Routine tasks such as log cleanup, certificate renewal and dependency updates.
- Expected costs of hosting and services each month.
See software maintenance costs after launch.
12. A live handover session
Documents are necessary but not sufficient. Schedule one or more recorded sessions where the developer walks your team or new developers through the code, deployment and common issues, and answers questions.
How to check the handover is real
- Ask a different developer to set up the project using only the documentation.
- Log into every listed account yourself.
- Restore a backup to a test environment.
- Deploy a small harmless change through the documented process.
If any step fails, the handover is incomplete. Hold the final payment until it is fixed, as your contract should allow.
A template for the architecture overview
Many handover documents fail because developers do not know what to include. This outline produces a useful overview in a few pages.
- Purpose: what the system does and who uses it, in three or four sentences.
- Components: each major part, for example web app, mobile app, API, admin panel, background workers, database, file storage, with one line describing its role.
- Diagram: boxes and arrows showing how components and external services connect.
- Hosting: where each component runs, which accounts own them, and environments such as staging and production.
- External services: payment gateways, SMS providers, maps, email services, with what each is used for.
- Data: main data entities and where sensitive data is stored.
- Scheduled jobs: what runs automatically and when, such as nightly reports or reminder messages.
- Security: authentication method, roles, where secrets are stored.
- Known limits: expected load, scaling approach, areas that will need work as usage grows.
Handover checklist by role
| Who | What they must be able to do after handover |
|---|---|
| Business owner | Log in to every account the system depends on, see monthly costs, understand renewal dates |
| New developer | Set up the project locally, understand architecture, deploy a change, roll back safely |
| System administrator | Monitor health, restore a backup, rotate credentials, renew certificates |
| Operations staff | Perform daily tasks, manage users, run reports, handle common issues |
| Finance | Know all recurring software and hosting costs and who is billed |
Test each row with an actual person from that role. If they cannot do it, the handover is incomplete for them.
Handover when a relationship ends badly
Not every handover happens between cooperative parties. Sometimes a freelancer stops responding or a vendor dispute escalates. Protect yourself before this happens by keeping ownership of accounts from day one. If you are already in a difficult situation:
- Secure ownership of the domain and hosting first, using business registration documents with providers if needed.
- Change passwords and remove the previous developer’s access once you have control, carefully, so nothing breaks unexpectedly.
- Back up everything immediately: code on the server, databases and uploaded files.
- Get an independent technical assessment of what exists and what is missing.
- Review the contract for ownership and handover obligations. See the software contract checklist.
An experienced team can often reconstruct a surprising amount from a live server, but it costs more than a proper handover would have.
Keeping documentation alive after handover
Documentation written once and never updated becomes misleading within months. Simple habits keep it useful:
- Store documentation in the same repository as code, so changes to code and docs happen together.
- Require documentation updates as part of completing any significant change.
- Record important decisions briefly: what was decided, why, and alternatives considered. See microservices versus monolith for the kind of decisions worth recording.
- Review the credentials inventory and cost list every quarter.
- Run a restore drill from backup at least twice a year.
Handover for mobile apps specifically
Mobile apps add items that are often forgotten: ownership of the Google Play and Apple developer accounts in the company’s name, app signing keys stored securely with backups, push notification service credentials, app store listing assets and descriptions, and build instructions for producing release versions. Losing an Android signing key can make it impossible to publish updates to an existing app listing, forcing a new listing and losing existing users and reviews. Treat these keys like the most important passwords in the company. See mobile app development cost in Pakistan for budgeting app projects properly.
What good handover costs
Proper documentation and handover sessions typically take a modest share of total project effort. That investment is small compared with the cost of a new team spending weeks reverse engineering an undocumented system, or a business losing access to its own software during a dispute. Include handover as an explicit milestone with its own acceptance criteria and payment.
Frequently asked questions
Will developers charge extra for documentation?
Good teams include it in the project. If it is not in the quote, ask for it explicitly before signing rather than at the end.
We already lost access to an old system. What now?
Start by recovering account ownership through domain registrars and hosting providers using company records. An experienced team can often reconstruct deployment knowledge from the live server. See legacy system migration without downtime.
Should documentation be in English or Urdu?
Technical documentation is usually written in English so any developer can use it. User guides for staff can be in whichever language the team is most comfortable with, including Urdu.
What tools are best for documentation?
Markdown files in the code repository work well for technical docs. A shared wiki or documents tool suits user guides and business procedures.
The bottom line
You only truly own software you can run, change and deploy without the original developer. Require code in your repository, accounts in your name, and documentation proven by someone else following it.
If you have inherited a system without documentation, our software team can help assess it and put a proper handover in place. Get in touch.