What should be included in a custom app handover document?

A complete handover document pack should include an architecture overview, local environment setup instructions, a deployment guide with rollback steps, documentation of all third-party integrations and where credentials are stored, a database schema or data model description, a list of known limitations or tech debt, and a runbook for common operational issues. Each document should be specific enough that a developer unfamiliar with the project can act on it without needing to ask questions.

How do I avoid being locked in to the agency that built my app?

The most important safeguard is ensuring all accounts and access are created under your organisation from the very start of the project. This includes the code repository, cloud hosting accounts, domain registrations, and any third-party service accounts the app depends on. Agree in writing that all credentials will be transferred and documented before final payment. A parallel working period and a post-handover support window also reduce dependency significantly.

How long does a proper custom app handover take?

A thorough handover for a typical internal tool or custom app usually takes one to three weeks when done properly. This includes time to write and review documentation, conduct a code walkthrough session, test setup instructions independently, complete an access audit, and run a brief parallel period. Rushing this phase to close a project quickly is a false economy; the cost of a confused internal team far exceeds the cost of an extra week of handover.

What makes custom software genuinely maintainable for a non-specialist internal team?

Maintainability comes from a combination of code quality and documentation. On the code side, the key factors are conventional project structure, proper dependency management, environment-based configuration (no hardcoded secrets), automated tests for critical functionality, and consistent code style enforced by a linter. On the documentation side, your team needs clear setup instructions, a deployment guide, and an honest account of known limitations. A non-specialist team can maintain a well-built tool confidently; even a good team will struggle with a poorly structured one regardless of how much documentation exists.

Should we ask to see the code before the project ends?

Yes. Requesting a code review or walkthrough before final sign-off is entirely reasonable and any reputable agency should welcome it. Use the review to check that the project structure is conventional, dependencies are properly managed, there are no hardcoded secrets, and critical functionality has test coverage. If an agency is reluctant to share the code before the final payment is made, that is a strong signal that the handover experience is likely to be poor.

How to Hand Over a Custom App to Your Internal Team

A successful custom app handover to your internal team requires four things: clean, well-structured code your developers can read without help; thorough documentation covering architecture, environment setup, and day-to-day operations; a structured knowledge-transfer period where your team can ask questions before the agency steps away; and full ownership of the repository, infrastructure credentials, and any third-party service accounts from day one. If any of these are missing, the tool becomes a black box, and your dependency on the original builder becomes permanent.

Why Custom App Handovers Go Wrong

The most common failure mode is not malicious lock-in. It is poor habits compounded over a project. Code gets written quickly without comments, environment variables are undocumented, deployment steps live only in someone's head, and by the time the project ends there is no appetite to go back and fill the gaps. For your internal team, picking up a codebase in this state can mean weeks of reverse engineering before they can safely make a single change.

A second failure mode is credential and access sprawl. If the agency created the AWS account, the Stripe webhook, the domain DNS records, and the Postgres database under their own umbrella, you may technically own the code but operationally you cannot move without them. Many UK businesses only discover this when they try to change provider or onboard a new developer.

What Good Handover Documentation Looks Like

Software handover documentation should be specific enough that a developer who has never seen the project can get it running locally, understand its structure, and confidently make a change within a day. Generic README files do not meet this bar. Here is what the documentation pack should include:

Architecture overview: A diagram or written description of how the components connect. Which services talk to which, where data lives, what happens when a background job fails.
Local environment setup: Step-by-step instructions to get the app running on a developer's machine from scratch, including every dependency, environment variable, and seed data step.
Deployment process: How code goes from a branch to production. Which CI/CD pipeline runs, what the rollback procedure is, and who holds the deployment keys.
Third-party integrations: Every external service the app calls, what it uses it for, and where the credentials are stored. This includes payment processors, email providers, analytics tools, and APIs.
Data model documentation: A schema diagram or plain-English description of the main database tables and the relationships between them.
Known limitations and tech debt: An honest list of corners that were cut, edge cases that are not handled, and anything the next developer should know before they start touching it.
Runbook for common issues: What to do when the most predictable things go wrong. Server is unresponsive, a cron job has not run, an integration has returned errors.

Tip

Ask your agency to write documentation as the project progresses, not as a final deliverable. Documentation written retrospectively is almost always thinner and less accurate than documentation written alongside the code.

The Handover Process: Step by Step

Establish ownership early. Before a line of code is written, confirm that all repositories, infrastructure accounts, and domain registrations will be created under your organisation's accounts, not the agency's. This is non-negotiable.
Define the documentation deliverables in the contract. Specify exactly which documents must be delivered and agreed before final payment is released. Vague wording like 'documentation will be provided' is not enforceable.
Schedule a code walkthrough session. Arrange a video call where the lead developer walks your internal team through the codebase. Record it. Watching a walkthrough is significantly faster than reading code cold.
Run a parallel period. If possible, have your internal developer working alongside the agency team for the final sprint or two. They will absorb context passively that no document can fully capture.
Test the setup instructions independently. Have someone on your team who was not involved in the project follow the local setup guide from scratch. Every step that fails or is missing should be fixed before sign-off.
Complete an access audit. Go through every service the app depends on and confirm your team can log in, rotate credentials, and make changes without the agency's involvement.
Agree a post-handover support window. A short period, typically two to four weeks, where the agency remains available to answer questions at no additional cost. This is reasonable to negotiate into any engagement.

App Documentation for Developers: Formats That Actually Work

The format of your app documentation matters as much as the content. Documentation buried in a Word document emailed at the end of a project is documentation that will never be found when it is needed. Consider where your team actually works and put the documentation there.

Format	Best For	Watch Out For
README in the repository	Setup instructions, architecture overview, quick-start guide	Gets stale if not maintained alongside the code
Internal wiki (e.g. Notion, Confluence)	Runbooks, process guides, decision logs	Can become disconnected from the actual codebase
Inline code comments	Explaining non-obvious logic, flagging known issues	Over-commenting simple code is noise; under-commenting complex code is the real problem
Recorded video walkthroughs	Onboarding new developers, explaining architectural decisions	Needs a written index so people can find specific topics without watching the whole thing
Architecture Decision Records (ADRs)	Capturing why a technology or approach was chosen	Requires discipline to write in the moment; hard to reconstruct retrospectively

Custom Software Maintainability: What to Look For in the Code Itself

Documentation is only part of the picture. A well-documented but poorly structured codebase is still hard to maintain. When assessing whether a custom app is genuinely maintainable, your developers should check for the following:

Conventional project structure: Code should follow the standard conventions of the framework being used, not an idiosyncratic layout that only makes sense to the original author.
Dependency management: All third-party libraries should be listed in a dependency file (package.json, requirements.txt, Gemfile, etc.) with pinned versions. No dependencies should be installed manually or outside this system.
Environment configuration: Secrets and environment-specific settings should be stored in environment variables or a secrets manager, not hardcoded in the source code.
Test coverage: There should be automated tests for the most critical parts of the application. Even a modest test suite provides a safety net when making changes and helps new developers understand expected behaviour.
Consistent code style: A linter or formatter should be configured so the codebase reads consistently regardless of who wrote which part.
No magic numbers or undocumented constants: Any value that is not self-explanatory should be named and explained.

Warning

If an agency is reluctant to share the codebase for review before project completion, or cannot explain their deployment process in plain English, treat that as a significant red flag for future maintainability.

How We Approach Handover at Bedrock Team

Our view is that a project is not finished until your team can own it without us. That means documentation is written throughout the build, not bolted on at the end. All repositories, cloud accounts, and third-party services are set up under your organisation from the start. We walk your team through the codebase, answer their questions, and confirm the setup guide works on their machines before we call it done. The goal is to make ourselves unnecessary, not indispensable.

If you are evaluating whether to commission a custom tool and are concerned about ending up with something your team cannot maintain, that is exactly the kind of question worth raising before the project starts. Get in touch and we can walk you through how we structure handovers and what we would deliver for your specific situation.