One-page architecture map for a messy prototype: a practical method

Why messy prototypes are hard to fix without a map

A messy prototype is confusing in a very specific way. Nothing is labeled, folder names sound important but mean nothing, and real behavior hides behind helpers and copy-pasted snippets. You click one button in the UI and three API calls fire, a background job runs, and data appears in a table that seems to be filled from somewhere else.

When you try to fix problems in a repo like that, you end up guessing. Guessing is expensive for two reasons: you waste time chasing the wrong file, and you create new bugs when you change something that looked unused but was quietly keeping the app alive.

A one-page architecture map helps because it gives everyone the same picture of how the app basically works. It’s not a perfect diagram, and it’s not documentation for every class. It’s a shared reference so the team can talk about the same thing.

Without a map, fixes often turn into:

• changing code near the bug, then discovering the real cause is two steps earlier
• patching the same issue in multiple places because logic is duplicated
• breaking auth, payments, or emails because a “small” change touched shared middleware
• missing external dependencies like webhooks, queues, or third-party storage

This approach is especially useful when the codebase is inherited, rushed, or generated by tools that produce working demos with shaky structure. Many AI-generated prototypes fall into this category: flows are implicit, and secrets, auth, and data rules are scattered.

A quick example: a founder reports “sign in works locally, fails in production.” Without a map, it’s easy to fixate on the login form. With a map, you can see the whole path: UI -> auth route -> database lookup -> cookie or token set -> middleware check on the next request. That view often shows where the flow actually breaks.

What makes a one-page architecture map useful

A one-page architecture map works when someone can read it in 60 seconds and say, “Yes, that’s how it works.” Once everyone agrees on the story, you stop arguing about guesses and start testing the right steps.

The best maps use plain words. Instead of folder names like src/services/authV2, label a box “Login and sessions.” Instead of api/routes, label it “HTTP endpoints.” This keeps the map readable for non-technical teammates, and it forces you to name what the code really does.

A one-page map also keeps you from over-documenting. You only show the paths that matter to the business and to the bugs you’re chasing. Most prototypes have a few critical journeys; everything else can wait.

Start with the flows that usually decide whether the app works:

• login and account creation
• the core workflow (the main thing users came for)
• payments (if you charge)
• emails, notifications, or webhooks
• uploads and downloads (if files are involved)

Arrows beat paragraphs. An arrow should answer: who calls whom, what data goes in, and what comes out. “Browser -> API -> Database” plus a note like “creates user record” is often more useful than a page of text.

Collect fast clues before reading lots of code

When a prototype has little or no documentation, your first job isn’t to understand every function. Your first job is to learn what the app claims to do, what it depends on, and where it touches the outside world.

Start with the files that “tell on” the project. A README (even a bad one) might mention the main features, hosting setup, or known issues. Dependency files like package.json, requirements.txt, or lockfiles quickly reveal the framework, database drivers, auth libraries, background job tools, and payment or email SDKs.

Then check how the app gets configuration. Look for .env.example, config templates, Docker files, and any notes about secrets. This is where you often discover missing keys, wrong callback URLs, or hardcoded tokens that work locally and fail after deployment.

If you want a fast checklist, focus on:

• What it runs on: framework and runtime (from dependency files)
• How requests enter: pages, API endpoints, webhooks, scheduled tasks
• Where data lives: migrations, schema files, seed scripts, ORM models
• What it talks to: auth, payments, email, file storage, analytics
• How it’s meant to run: deployment configs, CI files, “start” scripts

Example: an AI-generated app “works locally,” but users can’t log in in production. Before deep code reading, you spot an auth SDK in package.json, callback URLs in the env template, and an /api/auth route that expects a missing SECRET. That’s enough to sketch the key chain and to flag a real risk if secrets are exposed.

Find the entry points and main user flows

If you start mapping from random files, you’ll miss how people actually use the app. Start from entry points: the first places a real user or system touches your code.

Start with user entry points

Look for the screens that create the most state changes: landing page, sign-up/sign-in, the main “work” screen, and any admin area. Even in a messy prototype, these flows usually reveal the core data objects (users, projects, payments, files) and the key decisions (logged in vs not, free vs paid, role-based access).

A practical way to confirm the flow is to follow what happens after a button click: where does it send the user, what API call fires, and what gets stored (cookie, session, local storage, database row)?

Then capture technical entry points

In parallel, list every doorway into the backend. These are often the reason prototypes break in production.

• UI routes and main pages (including admin)
• API routes (REST/GraphQL), server actions, edge functions
• auth callbacks (OAuth redirects, magic links)
• webhooks from partners (payments, email provider, CRM)
• automations (cron jobs, queues, scheduled tasks)

External callers matter too. A browser isn’t the only client; a mobile app, an internal admin tool, or a partner system might call the same endpoints with different assumptions.

Example: an AI-generated app might let you “Sign in” on localhost, but in production the OAuth callback URL points to the wrong domain. Mark that callback as an entry point and add one note next to it: “Must match deployed URL, otherwise login loop.”

List the key modules without getting lost in folders

Messy prototypes often look bigger than they are. A fast way to get control is to group code by what it does, not where it sits in the folder tree. Your goal is a small set of modules that fit on one page.

Start by scanning for “gravity wells”: files that many others import or call. They usually reveal the real module boundaries, even when the repo structure is random.

A simple module inventory is:

• UI: pages, components, forms, and where network requests are triggered
• API surface: route handlers, controllers, middleware, request validation
• Business logic: workflows like “create account” or “checkout,” plus background jobs
• Data access: ORM models, raw queries, migrations, caching, file uploads
• Integrations: auth, payments, email/SMS, analytics, logs

After you have these buckets, assign files quickly. If a file feels like it belongs to two places, mark it as a “boundary” and move on. Boundary files are where bugs often hide (for example, UI components that build unsafe filters, or API routes that contain payment rules).

Example: an AI-generated app might have a folder named utils with 40 files. When you skim usage, you may find several clusters that are really “email sending,” “auth helpers,” and “data formatting.” Those clusters are your modules, even if the folders disagree.

Step-by-step method to sketch the map from the code

A good one-page architecture map is built from real behavior, not folder names. The fastest method is to pick one flow, follow it end-to-end, and draw only what you can prove.

Start with one flow you can actually trace

Pick a single core flow with a clear start and finish, like sign-up to the first successful action (creating a project, uploading a file, placing an order). Find the first entry point for that flow: a page, route, controller, or API endpoint.

Then trace each hop in order and turn each hop into a box. Don’t worry about perfect names. Use whatever the code calls it (for example, auth.ts, createProject, POST /api/upload). If you can’t follow a hop, stop and mark it as “unknown” instead of guessing.

Next to each box, capture a few essentials:

• what triggers it (button click, API call, cron job, webhook)
• what it returns (redirect, JSON, file URL, error)
• where state changes (database table, cookie, local storage)
• the main risk or assumption (missing validation, trusting client input)

Add services and trust boundaries as separate shapes

External services deserve their own boxes because they fail differently than your code. Common ones: auth providers, payment processors, email/SMS, object storage, analytics.

Then mark trust boundaries with simple labels on edges, like “browser to server” and “server to third-party.” This helps you spot where secrets, tokens, and personal data cross into places you don’t control.

Repeat the same method for two or three other critical flows until the page feels “full” but still readable. Login, password reset, and the main create-or-checkout action are usually enough.

Add security and data-safety notes as you map

A one-page architecture map isn’t just boxes and arrows. Add small security notes directly on the drawing while the code is fresh in your head. These notes often explain why a prototype works in demo mode but breaks (or becomes dangerous) in production.

Start with authentication. Mark where login happens, what creates the session or token, and what endpoints rely on it. If there’s password reset or OAuth, note the callback route and where the app stores state (cookies, local storage, server session).

Next, hunt for secrets. Write down where API keys and connection strings live, and where they might leak. In messy prototypes, keys often end up in client code, committed config files, debug logs, or error messages.

Then follow user input as it enters the system. Tag every boundary where untrusted data appears: forms, query strings, webhooks, file uploads, third-party callbacks. Add one note: “validated on server” or “UI only.”

For database safety, mark where queries are built. If you see raw SQL strings, dynamic filters, or string concatenation, flag it on the map. It’s a common source of SQL injection and data leaks.

Finally, note permissions. A route being behind “auth” is not the same as being authorized. Mark where role checks, ownership checks (user can only see their own records), and admin-only actions are enforced.

If you need a short annotation checklist, use:

• auth type and where it’s verified
• where secrets live and whether any are exposed
• where validation happens
• how the DB is queried (ORM vs raw SQL)
• where authorization rules are enforced

Common mistakes that make the map misleading

The goal is clarity, not completeness. The fastest way to ruin a one-page map is to treat it like a file index. You end up with a dense page that still doesn’t explain how the app behaves.

Another trap is naming boxes after tools instead of behavior. “Next.js + tRPC + Prisma” tells a developer what you used, but not what happens when a user signs in, uploads a file, or checks out. A map should read like a simple story: who calls what, what data moves, and what can fail.

Common mistakes:

• drawing every folder and missing the few flows that matter (sign-in, payments, admin actions, onboarding)
• naming boxes after tech stacks instead of actions (“Create invoice” beats “Backend service”)
• forgetting silent paths like cron jobs, queues, and incoming webhooks that only fail in production
• mixing environments (local mocks, fake keys, services that don’t exist after deployment)
• leaving out the data model, then wondering why business logic contradicts itself across screens

Assumptions aren’t the problem; hidden assumptions are. If you’re unsure whether “emails are sent by provider A” or “a job runs every hour,” write it as “assumed” or “unknown.” That turns confusion into a clear to-do.

Quick checks before you share the map

Before you send the map to a teammate or client, do a quick sanity pass. The goal isn’t perfection. It’s making sure the page tells the truth and points people to the right questions.

Try this: can you explain the main user flow in under two minutes using only what’s on the page? If you keep saying “and then some stuff happens,” add one missing box or arrow.

Five checks that catch most issues:

• every external service appears somewhere (auth, email/SMS, payments, file storage, analytics)
• at least one clear “data store” box exists (database, object storage) with read/write arrows
• trust boundaries are visible (client, your server, third parties)
• entry points are obvious (routes, endpoints, jobs, webhooks)
• the top risks are visible (auth/session handling, secrets, input validation)

After that, add a small “Unknowns” corner with up to five items. Make them specific so someone can confirm them quickly.

Example: mapping an AI-generated prototype that breaks in production

A founder inherits a Bolt or Lovable prototype that looks fine on localhost, but falls apart after deployment. Users can open the landing page, yet sign-up fails and nobody can log in.

Start with one real user action: “Create account.” You don’t need perfect boxes. You need the few boxes that explain what talks to what, and where data changes.

A typical map for this situation includes:

• browser UI (signup form) calls a server action or API route
• server code talks to an auth provider and receives a callback
• server writes a user row to the database
• an email service sends verification messages
• environment variables supply keys and callback URLs

Now trace the failing step in production. The UI submits, the server redirects to the auth provider, then the callback returns to a different domain than expected because the callback URL is still set for localhost. In worse cases, the client bundle contains an auth secret because it was stored in a public env var.

While you map, add small red-flag notes that make the first fixes obvious:

• exposed secret in client-side config
• missing role or ownership checks on sensitive endpoints
• inconsistent table names (users vs user, profile vs profiles)
• auth callbacks pointing to localhost or the wrong domain

The outcome isn’t a pretty diagram. It’s clarity and a safer fix order.

Next steps: turn the map into a repair plan

A one-page architecture map only matters if it changes what you do next. Use it to turn “random bug fixing” into a clear order of work, so you tackle the most blocking risks first.

A practical fix order for most messy prototypes:

• stabilize authentication and sessions (login, roles, token storage, password reset)
• confirm the data model (tables, relations, migrations, validation points)
• repair the core user flow (the one action the product must do end-to-end)
• handle extras (notifications, analytics, admin tools)

Then decide whether you should patch, refactor, or rebuild:

• Patch when the flow is clear and problems are isolated (one broken integration, a few bad queries).
• Refactor when the app works but the structure fights you (duplicate logic, unclear boundaries).
• Rebuild when the map shows spaghetti architecture (everything talks to everything, secrets are scattered, no safe place to add checks).

Keep the one-pager alive while you repair. Each time you move responsibility (for example, centralizing database access or pulling auth checks into middleware), update the map so the team doesn’t fall back into guesswork.

If you want a second set of eyes on an AI-generated codebase, FixMyMess (fixmymess.ai) starts with a codebase diagnosis and can help repair issues like broken authentication, exposed secrets, and unsafe data access before you sink time into rewrites.