Mobile App Mapping: Screens, States, User Flows & Variants in Production

Your app already has plenty of documentation. Figma shows the app design. The codebase shows what the application can render. Analytics shows what has been instrumented. QA documents what was expected to work. Session replay shows what users encountered in individual sessions.

Each source is useful. The problem starts when you need to answer a different question: What actually exists in the app right now, and how does it all connect?

A mobile app map can provide that missing structure. Instead of listing screens in isolation, it connects app screens, screen states, actions, transitions, and user journeys across the production environment.

That's the problem Tugboat Manifest is built to address.

An app changes after it ships. Features gain new states, navigation changes, experiments introduce alternate experiences, releases modify existing behavior, and users reach the same part of the product through different entry points. The documentation does not always change at the same pace.

An app design layout may show the intended experience. QA may document the scenarios the team expects to work. Analytics may show which events have been instrumented. A session replay may show what happened during one user's session. None of these gives the team a complete view of the existing product and its connected runtime structure.

This is where representation drift appears. The production product changes while its design, documentation, tests, and instrumentation change at different speeds.

A basic screen inventory has the same limitation. It might tell you that an app contains a Cart, Address, Payment, and Confirmation screen. It does not tell you what states those screens can have, which actions are available, or how users move between them. A useful mobile app map needs to show those relationships.

A production product map is a connected representation of the screens, states, actions, and transitions in a running product. It can organize those elements into user flows and journeys while accounting for production differences such as builds, variants, and locales.

The basic model is:

State → Action → Transition → State

For example:

Payment Failed → Retry → Loading

The transition does not have to take the user to another screen. In this case, Retry changes the Payment screen from a failed state to a loading state. That distinction matters when mapping an existing product because two identical screens can behave differently depending on their current state.

You can search for a screen, state, or component, follow a journey or path, find related product objects, and see how builds, variants, and locales affect the experience.

Like Google Maps shows alternate routes, a product map can show different paths based on account state, permissions, configuration, or experiments. This gives teams a clearer view of the runtime behavior of the product instead of relying only on screens or screenshots.

One of the easiest ways to make an app map misleading is to treat every mobile app screen as a single state.

Consider Checkout. The same screen might appear when the cart is empty, after products have been added, after a promotion has been applied, while payment is processing, or after payment has failed.

For example:

Checkout: Empty · Populated · Promo Applied · Payment Loading · Payment Failed · Payment Complete

The interface may look similar across several of these states, but the available actions and product behavior can be very different.

The same applies to app behavior. A user may see a loading indicator, retry button, permission request, error message, or confirmation without leaving the current screen.

A production map should therefore distinguish between:

• Screens: The visible parts of the application.
• States: The conditions in which those screens can exist.
• Actions: What the user can do.
• Transitions: How the application responds to those actions.

This is also where UI and UX become relevant. UI describes what users see and interact with, while UX covers the broader experience as they move through the product. A production map connects those interface states and interactions to the actual paths available in the shipped app.

RELATED READING: How to Detect a Product Regression Before Your KPI Moves

Mobile app design is an important part of product development. Design teams use screens, components, screenshots, prototypes, and design systems to communicate how an experience should work. A typical app design layout might show:

Cart → Address → Payment → Confirmation

That gives product teams, designers, and engineers a clear picture of the intended experience. The same is true of app mobile design work more broadly.

Designers can define the visual hierarchy, interaction design, components, and user flows before an experience reaches production. But the shipped product can contain more than the original design.

The Cart screen may have empty and populated states. Address may have valid, invalid, and permission-blocked states. Payment may include loading, verification, failure, retry, and completion states.

The difference is important because mobile app examples and design references usually show selected experiences. A production product map needs to account for the states and paths users can actually encounter.

Checkout makes the difference between design intent and production reality easy to see. A simple design flow might look like this:

Cart → Address → Payment → Confirmation

In production, it could look more like:

Now add production variation. An experiment might expose PayPal. A newer build might introduce a verification state. A deep link might send a user directly to Payment.

Variant B → PayPal v7.14 → Verification state Deep link → Payment

The original design still has a purpose. It documents the intended checkout experience. The production map answers a different question: what states, transitions, entry points, and variations exist in the product users can encounter?

A runtime map should not imply that everything theoretically possible in an application has been proven to exist. Some states may sit behind feature flags, require a particular account or permission, depend on a server response, or be so rare that they have not yet been reached.

That means a useful production map needs more than nodes and edges. It needs to make its coverage and provenance clear: where a state came from, which build or variant it belongs to, when it was last observed or represented, and what remains unexplored.

For example:

The point isn't to make every map perfectly complete. It is to make its limits visible. A production map is only as trustworthy as its coverage and provenance.

This also changes how teams should interpret the map. A state that has not been observed or otherwise established by the mapping process should not automatically be treated as part of the known production structure simply because the code could theoretically produce it.

A useful production app map needs more than a list of screens. It should show the structure that connects the application's interface, behavior, and journeys.

Several tools already describe parts of a product. They answer different questions.

A sitemap focuses on hierarchy and navigation. A user flow focuses on a defined journey. An architecture diagram describes technical components and their relationships. Session replay shows what happened during an individual user's session.

A production product map connects the screens, states, actions, and transitions that make up the running product. That does not make it a replacement for the other representations.

Figma remains useful for design intent. A design system remains useful for defining reusable components. Analytics remains useful for understanding events and usage. Screenshots remain useful for documenting what an interface looks like. Session replay remains useful for examining individual user behavior.

The product map gives teams a shared structure for placing these different sources in context.

Once the production product has a connected representation, different teams can ask questions about the same structure.

Product: Is Variant B still live in checkout?

Engineering: What transitions can lead to Payment Failed?

Design: Which production states are missing from the current Figma flow?

QA: Which reachable states are not covered by the current test plan?

Developers: Where does this screen appear elsewhere in the product?

Product managers: Which user journeys depend on this feature?

These questions are easier to answer when teams can work from the same representation of the existing product.

A teammate can ask which Payment screen you mean. An agent faces the same ambiguity. Before it can investigate an issue or make a useful change, it needs to know which part of the product the task refers to.

A screenshot shows an interface at one moment. The map adds the context around it: how that state was reached, what action changed it, what happens next, and where else it appears. A coding agent can inspect the repository; the map connects that implementation to the product users actually encounter.

That context can help agents investigate issues, review states, plan test coverage, or prepare code changes. The map defines the product context; repository access, design references, and execution tools provide the evidence needed to act.

Tugboat Manifest turns the production product into something teams can inspect and navigate. It connects screens, states, and transitions so teams can trace how a production state is reached, what happens next, and where else that state appears.

Manifest represents the production product alongside the systems teams already use to build, test, and observe it.

Figma can represent design intent. The codebase remains the implementation source. Analytics explains instrumentation. QA defines testing expectations. Session replay provides session-level evidence.

Manifest adds a connected view of the production application. Coverage also matters. When a state or transition has been observed or established, that context helps teams understand what the map represents. When part of the application has not been reached or verified, that limitation should remain visible.

The result is a production map that gives teams more context around the product behavior, app behavior, states, transitions, and journeys they are working with.

A shipped app already has documentation across design files, code, QA, analytics, screenshots, session replay, and other tools. Each source describes part of the product. A mobile app map brings another layer into view: the connected structure of the production product.

It shows the app screens and states users can encounter, the actions that connect them, the user flows that run through them, and the differences introduced by builds, variants, locales, and other production conditions. For teams working on an existing product, that structure provides a clearer way to understand what shipped and how its parts connect.