Understanding File Structures in AI Prototyping
Navigating Code Like a Pro
Hey, I’m Colin! I help PMs and business leaders improve their technical skills through real-world case studies. For more, check out my live courses, Technical Foundations and AI Prototyping.
As AI tools become more accessible, many product managers find themselves exploring code for the first time. Understanding how files are organized in an application can feel overwhelming at first, but it's a crucial skill for effective AI prototyping and development.
Let's break down the fundamental concepts of file structures through the lens of a modern web application, similar to what you might create using tools like Replit, v0, or Bolt.
JavaScript Frameworks for Modern Applications
Before diving into file structures, it's important to understand that most AI tools today generate code using popular JavaScript frameworks. These frameworks provide pre-built structures and patterns that make development faster and more consistent.
Client-Side Frameworks
The most common frameworks you'll encounter in AI-generated code include:
React - This is the most popular framework for building user interfaces. Most AI tools (v0, Bolt, Lovable) default to React.
Next.js - Built on top of React, Next.js adds features like server-side rendering and simplified routing. This is the default for tools like v0.
Vue - An alternative to React with similar capabilities but different syntax.
Server-Side Frameworks
For applications that need server functionality:
Node.js with Express - The most common server-side JavaScript environment and framework
Next.js API Routes - Next.js can handle both client and server code in one framework
Python with Flask/Django - Some tools like Replit support Python server frameworks
We'll focus primarily on React and Next.js patterns since they're the most commonly used in AI development tools today. Understanding these patterns will help you navigate code generated by v0, Bolt, Replit, and similar services.
The Three-Tier Architecture
Most web applications follow what developers call a "three-tier architecture":
Client - What users interact with (the UI)
Server - Processes requests from the client
Database - Stores data permanently
Think of these as distinct layers that communicate with each other. When you build with tools like v0 or Bolt, you're often only working with the client tier, while platforms like Replit allow you to build all three tiers.
Client-Side File Organization
The client-side code is like a set of Lego blocks that fit together to create what users see. Let's examine how these files are typically organized:
App.tsx - The Main Container
Every client application has a main file (often called App.tsx or index.js) that serves as the container for everything else. This file typically:
Imports components from other files
Sets up routing (navigation between pages)
Renders the overall application structure
Think of this as the foundation upon which everything else is built. Here's what an App.tsx file might look like:
This file brings together all the pages and main components, defining how users navigate between different sections of the app.
Pages and Components
Applications are built using a component-based approach, where UI elements are broken down into reusable pieces:
Pages - Complete screens users navigate between (like Dashboard, Contacts, Settings)
Components - Smaller, reusable pieces that make up pages (like buttons, tables, forms)
For example, a Companies page might import smaller components like:
CompanyTable (to display data)
CompanyForm (to add new companies)
SearchBar (to filter companies)
These smaller components might themselves be built from even more basic elements like buttons, input fields, and text. The component structure allows for reuse and easier maintenance.
Hooks - Client-Side Logic
Besides visual components, modern applications use "hooks" to handle logic. These are reusable functions that provide specific functionality across the application:
useMobile - Might detect screen size to adjust layout for mobile devices
useModal - Open and closing a modal
useAuth - Might handle user authentication
Here's what a simple hook might look like:
These hooks encapsulate behaviors that might be needed throughout the application.
Server-Side File Organization
If you're working with a three-tier architecture (like in Replit), the server tier typically includes API endpoints and a database.
Routes/API Endpoints
Server-side code is organized around "routes" or "endpoints" - specific URLs that the client can request data from or send data to. Common patterns include:
GET /api/companies - Retrieve all companies
POST /api/companies - Create a new company
PUT /api/companies/123 - Update company with ID 123
DELETE /api/companies/123 - Delete company with ID 123
Here's what server routes might look like in an Express.js application:
These routes connect client actions to database operations.
Data Models
The data model defines the structure of your information - think of it like a set of interconnected spreadsheets:
Tables - Different types of data (Users, Companies, Contacts, Tasks)
Fields - Properties within each table (name, email, status)
Relationships - How tables connect to each other (a Task belongs to a Contact)
A simple data model definition might look like:
Understanding your data model is crucial because it impacts both how data is stored and how it's displayed in the UI.
Making Changes Across Tiers
When you want to make changes to an application, understanding which tier(s) need modification is key:
UI changes only (like changing colors or layout) - Modify client files only
Adding a new field to a form - Update all three tiers:
Client: Add the field to the form
Server: Update the API to accept the new field
Database: Add the field to the data model
This is where having a mental model of the application structure becomes valuable. When using AI tools to modify code, you can be more specific about what needs to change.
When working with AI tools like Claude, GitHub Copilot, or code generation in v0/Bolt, keep these tips in mind:
Start with the data model - Define what information your application needs to store before designing UI
Be specific about file locations - Tell the AI exactly which file you want to modify
Explain tier impacts - Mention whether changes affect client, server, database, or all three
Provide context - Share relevant surrounding code or explain the purpose of files
For example, rather than saying "add a status field to contacts," you might say:
"Add a status field to ContactForm.tsx. Also update the server route at routes/contacts.js to handle this new field, and add the field to the contacts table in the database."
Putting It All Together
Understanding file structure isn't just about knowing where code lives—it's about grasping how different parts of an application relate to each other. When you can conceptualize these relationships, you'll be able to:
Better communicate with AI tools about what changes you want
More easily identify which files need modification
Understand potential impacts when making changes
This knowledge is particularly valuable as you move from basic prototypes to more complex applications that store and process data.
Remember that different tools organize files differently—v0 works differently from Replit, which works differently from a custom codebase. But the fundamental patterns of components, pages, hooks, routes, and data models remain consistent across most modern applications.
By understanding these basics, you'll be better equipped to navigate, modify, and create applications—even if you're not writing every line of code yourself.