Mobile App Architecture Documentation: C4, ADR, Onboarding

Architectural documentation of a mobile application: bottlenecks

A mobile application grows modules over the years: networking layer, local cache, background synchronization, navigation, screen rendering.

While the structure and connections between parts live in the heads of two developers, any edit turns into reconnaissance—to fix list display, an engineer reads five files and still cannot say in advance what else the change will affect.

The cost of such uncertainty is measured not in points but in timelines.

A new person on the team reaches their first independent edit not in a week but in a month; enhancements drag side regressions in the most unexpected places—from the checkout screen to incoming notification handling.

Decisions are made blindly: no one remembers why the cache is designed this way and what will break if it is removed.

Architectural bottlenecks are almost always the same: there is no description of architecture as such, that is, layers and dependency direction, module boundaries are not fixed, and there is no decision history—why this synchronization method was chosen and what was rejected.

Without this, analysis of the application structure starts anew with every major change, and timeline estimates rely on intuition.

That is why mobile application architectural documentation for us is a living artifact, not a folder with pictures: a level diagram in C4 notation, short records for each significant decision, a module dependency map, and an onboarding route. Next we break down what such a kit consists of and how it stays current.

Effect: speed of onboarding newcomers, releases, rollbacks

Documentation pays off not by the mere fact of its existence, but because its absence is visible in the calendar.

Therefore, before work starts we fix four measurable values: time to the first accepted edit by a new engineer, share of releases that miss the planned date, number of reworks due to misunderstood requirements, and time to return to the previous stable build.

• Developer onboarding. Instead of three to four weeks to parse someone else's logic—5-7 working days to the first independent edit: module boundaries, data schema, and connections between services are described in C4 notation, diagrams are generated from Structurizr, not drawn by hand, so they do not diverge from the code.
• Independence from a single engineer. Each significant decision lives as an ADR: context, considered alternatives, consequences, and review conditions. The knowledge holder ceases to be a single point of failure—a vacation or departure does not stop the direction.
• Release predictability. The share of unplanned rework drops: integration seams, migration order, and dependencies between modules are known before work starts, not discovered at acceptance.
• Rollback. A pre-described order of returning to a stable version—reversible migrations, local storage state, sequence of steps—reduces recovery after a failure from hours to minutes.

We measure these indicators not once: documentation is updated in the same change as the code, otherwise after several iterations the numbers return to baseline.

Architecture description formats: diagrams, decisions, rules

No format describes the application entirely—each has its own scope and its own cost of keeping it current. Overview diagrams onboard a new engineer and fix system boundaries, decision records prevent reopening closed questions, and release policy handles operations. Below is an honest comparison: where a format is strong and where it stops working.

The set covers three different questions: how it is designed, why so, and how it is released. If only diagrams are left, decisions will be reopened with every new team; if only records—a new engineer will not see the system as a whole. Therefore we keep the formats in one place and link them.

Work stages: from interviews to handover to the team

The customer needs not a stack of diagrams but a description that matches the code and works without its author. Therefore we go from facts to document: first we analyze the current state, then design the structure, and in the end test the result on live tasks.

The stage order is fixed—it protects against describing "as intended" instead of "as is."

1. Audit of the current architecture. We read repositories, build configuration, and module boundaries, and reconstruct real dependencies between layers. We record discrepancies: where the diagram on the board does not match what compiles and ships to release.
2. Interviews with the development team. For each layer we extract unspoken agreements, historical decisions, and workarounds—without them the description is formally correct and useless in practice.
3. Designing the description structure. We determine which C4 levels this product needs, for which topics we create ADRs, and what goes into newcomer onboarding. We agree on the section composition before writing so we do not rewrite.
4. Filling. We collect diagrams, ADRs with context, decision, and consequences, a glossary, and an integration point map. Each diagram is supplied with a link to the code section it describes.
5. Testing diagrams on real scenarios. We run typical tasks—add a screen, replace an external service, release—and check whether the description is enough to complete the path without looking into the code or asking the author each time.
6. Handover of the description to the team. We conduct a walkthrough with developers, place the documents next to the code, and agree on the rule: a significant decision is recorded as an ADR in the same change set as the code.

After handover, the team has an entry point for a new engineer and a living source of truth on architecture—it updates together with the product, not through a separate heroic effort once a year.

Deliverables: diagrams, policies, access

After delivery, the customer has not a presentation but a working kit: it is used for on-call, releases, rollbacks, and onboarding new engineers into the project.

Artifacts live next to the code and are edited in the same change set—a document that diverges from reality is considered defective.

• C4 architecture map: context, containers, and components—what the application consists of, what external dependencies it has, and where service boundaries lie.
• Integration diagrams: network, queues, storages, offline mode—with a description of what happens when each side is unavailable.
• Access policies and roles: rights of developer, tester, support, and contractor, procedure for granting and revoking access to builds and storages.
• Release policy: branching, mandatory checks, and confirmation points before publication—who records what at each step.
• Rollback policy: degradation signs, trigger threshold, and action sequence, including the fate of user data.
• Architectural decision log: what was chosen, which alternatives were rejected and why—logic is not reconstructed from chat.
• Onboarding guide: how to set up the environment, build the build, and where the key modules are.

We test the kit on a live scenario: an engineer who did not participate in the project deploys the environment and makes the first edit using the documents. Where they stumble—we update the diagram or policy, not explain verbally.

Case study: cut onboarding time for new developers in half

An application for two platforms, four product teams, distributed hiring. Documentation at the start was like this: a dozen diagrams in shared storage, some without dates and no longer matching the code, architecture decisions lived in chat history.

A new developer pieced the picture together from code and chat questions: the first independent production change took five to six weeks.

We consolidated everything into one loop. We keep C4 context and containers as code in Structurizr—the model sits next to the repository and rebuilds automatically, no one draws diagrams by hand.

For each significant decision—a short ADR: context, considered options, chosen one, consequences. Three pages appeared separately that had not existed before at all: a map of modules and their boundaries, data flows between them, and build and release order.

Architecture changes now go through the same code review as edits: if a decision changes module boundaries, updating the diagram and ADR is part of the same branch. This removed the main source of divergence—documentation edited "later."

What changed after:

• onboarding time for a new developer—from five to six weeks to two and a half;
• first independent release—on the seventh to ninth working day instead of the fifth week;
• share of post-release failures—from ~18% to 5%, and almost all remaining ones at seams with external services, not inside the product.

The key here is not the volume of documentation but a single entry point: a person sees the application structure, its boundaries, and the reasons for decisions in one evening. Then they change the code without breaking hidden contracts.

How does an architectural decision differ from a technical specification?

A technical specification answers the question "what to do": which screens and scenarios exist in the application, where data comes from, and by what criteria the work will be accepted.

This is a scope and acceptance document—it is used to estimate effort and close stages. But it does not explain why this structure was chosen and which alternatives were rejected.

An architectural decision and a technical specification are not competing documents but different levels of description.

A decision fixes the reasons: why state is stored locally instead of requested on each screen; why background synchronization is separated; what happens if the network drops in the middle of an operation.

What distinguishes a decision description is that next to the choice stands the rejected alternative and the cost it came with.

The boundaries of a decision's applicability are the most underestimated part. It directly states up to what data volume the design holds the load and where it breaks: for example, when switching to full offline mode or when a second sales channel appears.

Without this boundary, the next engineer either fears touching working code or breaks it without understanding what held the system together.

The difference is visible when a team changes: the specification reads as a list of facts, the decision as an explanation, so a new developer joins the project in days, not months.

We maintain both documents in parallel and update the description with every architecture change—otherwise it quickly turns into fiction.

Common doubts: support, access, changes

Doubts usually concern not the documentation itself but accompanying conditions: the product has long been in production, access must be granted to someone, and the description becomes outdated faster than it can be read. Let us break down three questions that come up most often before work starts.

Separately about changing contractors: materials must reside in the customer's environment, not in someone else's storage, otherwise understanding of the system leaves together with the team. Below is how this works in practice.

Who will get access to the documentation, and with what rights?

We place the materials in the customer's repository: developers—write via mandatory review, analysts and department leads—read. Edits to the architecture description and ADRs go through the same approval process as code, so the history shows who changed the decision and why.

How does the description stay current when the team changes?

Freshness is embedded in the process, not in a verbal agreement: an architecture change without updating the corresponding section does not pass the merge check, and diagram review is part of the release checklist. A new engineer or contractor joins the project by document, not by stories from the previous team.

Let's discuss your task and come back with a plan

So that the start of architecture description does not stretch into months of correspondence and clarifying questions, it is enough to gather a few inputs for the first conversation. Nothing exotic—usually the team running the product already has this. From this data we immediately see the system boundaries and the scope of future documentation.

• Target platforms and minimum supported operating system versions.
• List of user roles and 5–10 key scenarios the application must cover.
• List of external systems for integration—payments, analytics, internal services—and data exchange formats with them.
• Access to repositories, issue tracker, and mockups: read-only is enough.
• Current documentation and decisions that cannot be changed: exchange contracts, data schemas, security requirements.
• Release timeline constraints, regulatory requirements, and offline operating modes.
• The person responsible for decision acceptance on the customer side—one person, not a committee.

The format does not constrain us: we work with C4 diagrams, an ADR-style decision log, and textual descriptions for onboarding new developers.

Describe the task in free form—we will come back with an estimate and work plan: document composition, preparation order, and points where your confirmation is needed.