3.7 Generating the File Structure

The file structure defines how your application's code is organized into files and folders. It creates a logical, scalable architecture that makes your codebase easy to navigate, maintain, and extend. In VibeMap, the file structure is automatically generated based on your pages, components, and database schema.

What Is a File Structure?

A file structure organizes your application code into:

• Folders - Logical groupings of related files

• Files - Individual code files with specific purposes

• Architecture patterns - Common organizational approaches (MVC, component-based, etc.)

• Naming conventions - Consistent file and folder naming

• Import/export structure - How files reference each other

• Configuration files - Settings, build tools, and environment configs

How File Structure Generation Works

VibeMap's file structure generation is intelligent and contextual - it doesn't create files from scratch, but rather builds upon the project artifacts you've already created:

Pre-Existing Entities (Not Generated)

These files are automatically included based on your previously created project artifacts:

• 📄 Pages - Derived directly from your Pages & Components generation

• 🧩 Components - Derived directly from your Pages & Components generation

• 🗄️ Database Schema - Derived directly from your Database Schema generation

• 🧪 Tests - Derived directly from your User Stories and Acceptance Criteria

Generated Files (Created by File Structure)

When you click "Generate File Structure", VibeMap creates all the supporting files needed for a comprehensive full-stack Next.js application:

• 🔧 Backend Logic - API routes, server actions, business logic

• 📚 Type Definitions - TypeScript interfaces and types

• 🎣 Custom Hooks - React hooks for state management and data fetching

• 🛠️ Utilities - Helper functions, validation, formatting

• ⚙️ Configuration - Build tools, environment settings, deployment configs

• 🔒 Security - Authentication, authorization, validation middleware

• 📱 Styling - CSS modules, Tailwind configurations, global styles

• 📖 Documentation - README files, API documentation, setup guides

Prerequisites

Before generating a file structure, you need to have created these project artifacts:

Required Artifacts

• 📄 Pages & Components - Provides the UI structure and component hierarchy

• 🗄️ Database Schema - Defines the data layer and database relationships

• 📋 User Stories - Used to generate comprehensive test files

• ✅ Acceptance Criteria - Provides detailed test scenarios and validation rules

Additional Context

• 🎯 Project Features - Helps determine overall architecture and business logic

• 👤 User Personas - Influences authentication and user management files

• ⚙️ Technical Preferences - Framework, language, and tool choices from your project description

Note: The file structure is automatically generated when you create a project, but you can regenerate or modify it from the File Structure section. The more artifacts you have created, the more comprehensive and accurate your file structure will be.

How to Generate the File Structure

Automatic Generation (Recommended)

The file structure is created automatically during project creation. VibeMap analyzes your pages, components, and schema to generate a comprehensive codebase organization.

Manual Generation

To regenerate the file structure or create additional structure elements:

1. Navigate to File Structure: Click the "File Structure" tab in your project sidebar

2. Click "Generate File Structure": Creates a complete codebase organization

3. Wait for Processing: Takes 3-5 minutes for complex projects

4. Review Results: Structure appears as a hierarchical tree with detailed file descriptions

Generating Additional File Structure Elements

If you need more files or folders:

1. Click "Generate Additional File Structure Elements": Creates new elements without duplicates

2. AI analyzes existing structure: Avoids repetition and identifies gaps

3. Focuses on missing functionality: Covers areas you might have missed

4. Adds supporting files: Creates files for edge cases and advanced features

What You'll Get

Complete File Structure Organization

Your generated file structure will include both pre-existing entities and newly generated files:

Pre-Existing Files (From Previous Generations)

• 📄 Pages - All pages from your Pages & Components generation

• 🧩 Components - All components from your Pages & Components generation

• 🗄️ Database Files - Schema files, migrations, and models from your Database Schema generation

• 🧪 Test Files - Comprehensive tests derived from your User Stories and Acceptance Criteria

Newly Generated Files (Created by File Structure)

• 🔧 Backend Logic - API routes, server actions, business logic, data access layers

• 📚 Type Definitions - TypeScript interfaces, types, and type guards

• 🎣 Custom Hooks - React hooks for state management, data fetching, and UI interactions

• 🛠️ Utilities - Helper functions, validation schemas, formatting utilities, constants

• ⚙️ Configuration - Build tools, environment settings, deployment configurations

• 🔒 Security - Authentication middleware, authorization helpers, validation utilities

• 📱 Styling - CSS modules, Tailwind configurations, global styles, component styles

• 📖 Documentation - README files, API documentation, setup guides, contribution guidelines

Example File Structure

src/
├── components/                    # 📄 From Pages & Components Generation
│   ├── ui/
│   │   ├── Button.tsx           # Pre-existing
│   │   ├── Input.tsx            # Pre-existing
│   │   └── Modal.tsx            # Pre-existing
│   ├── forms/
│   │   ├── LoginForm.tsx        # Pre-existing
│   │   └── UserProfileForm.tsx  # Pre-existing
│   └── layout/
│       ├── Header.tsx           # Pre-existing
│       ├── Sidebar.tsx          # Pre-existing
│       └── Footer.tsx           # Pre-existing
├── pages/                        # 📄 From Pages & Components Generation
│   ├── dashboard/
│   │   └── index.tsx            # Pre-existing
│   ├── auth/
│   │   ├── login.tsx            # Pre-existing
│   │   └── register.tsx         # Pre-existing
│   └── profile/
│       └── index.tsx            # Pre-existing
├── lib/                          # 🔧 Generated by File Structure
│   ├── api.ts                   # Newly generated
│   ├── auth.ts                  # Newly generated
│   └── database.ts              # Newly generated
├── types/                        # 📚 Generated by File Structure
│   ├── user.ts                  # Newly generated
│   ├── project.ts               # Newly generated
│   └── index.ts                 # Newly generated
├── hooks/                        # 🎣 Generated by File Structure
│   ├── useAuth.ts               # Newly generated
│   ├── useProjects.ts           # Newly generated
│   └── useLocalStorage.ts       # Newly generated
├── utils/                        # 🛠️ Generated by File Structure
│   ├── validation.ts            # Newly generated
│   ├── formatting.ts            # Newly generated
│   └── constants.ts             # Newly generated
├── styles/                       # 📱 Generated by File Structure
│   ├── globals.css              # Newly generated
│   ├── components.css           # Newly generated
│   └── utilities.css            # Newly generated
├── tests/                        # 🧪 Generated from User Stories & Acceptance Criteria
│   ├── components/
│   │   ├── Button.test.tsx      # Derived from acceptance criteria
│   │   └── LoginForm.test.tsx  # Derived from user stories
│   ├── pages/
│   │   ├── dashboard.test.tsx   # Derived from acceptance criteria
│   │   └── auth.test.tsx        # Derived from user stories
│   └── utils/
│       ├── validation.test.ts   # Derived from acceptance criteria
│       └── api.test.ts          # Derived from user stories
└── database/                     # 🗄️ From Database Schema Generation
    ├── schema.sql               # Pre-existing
    ├── migrations/              # Pre-existing
    └── models/                   # Pre-existing

File Descriptions

Each file includes:

• Purpose - What the file does and why it exists

• Dependencies - What other files it imports

• Exports - What functionality it provides to other files

• Implementation notes - Key considerations for development

• Testing requirements - What tests should be written

Managing Your File Structure

Viewing Structure Details

Click on any file or folder to see:

• Complete file description and purpose

• Import/export relationships with other files

• Implementation requirements and considerations

• Dependencies and external libraries needed

Editing File Structure

• Click "Edit" on any file or folder

• Modify names, descriptions, or organization

• Add or remove files and folders

• Update file relationships and dependencies

• Save changes to update the structure

Adding New Files

1. Click "Add File" button

2. Choose folder location and file name

3. Enter file description and purpose

4. Set dependencies and relationships

5. Save to add to your structure

Adding New Folders

1. Click "Add Folder" button

2. Enter folder name and purpose

3. Choose parent location in the structure

4. Set organization rationale

5. Save to add to your structure

Expected Outcomes

Comprehensive Full-Stack Application

When you click "Generate File Structure", you'll get a complete, production-ready Next.js application structure that includes:

Pre-Existing Files (From Previous Generations)

• All pages and components from your Pages & Components generation

• Complete database schema and migration files from your Database Schema generation

• Comprehensive test suite derived from your User Stories and Acceptance Criteria

Newly Generated Supporting Files

• Complete backend infrastructure - API routes, server actions, business logic

• Full TypeScript type system - Interfaces, types, and type guards

• Custom React hooks - State management, data fetching, UI interactions

• Utility functions - Validation, formatting, constants, helpers

• Configuration files - Build tools, environment settings, deployment configs

• Security implementation - Authentication, authorization, validation

• Styling system - CSS modules, Tailwind config, global styles

• Documentation - README, API docs, setup guides

Typical Generation Results

• 50-150 total files for most applications (varies by complexity)

• 10-20 top-level folders covering all functional areas

• Complete separation between frontend, backend, and shared code

• Production-ready architecture that can scale with your application

• Comprehensive test coverage based on your user stories and acceptance criteria

Quality Indicators

Good file structures will have:

• ✅ Logical organization and clear naming

• ✅ Appropriate separation of concerns

• ✅ Consistent patterns and conventions

• ✅ Clear dependencies and relationships

• ✅ Scalable and maintainable architecture

Best Practices

Writing Effective Project Descriptions for File Structure

To get better file structures, include in your project description:

• Technology stack - Framework, language, and tools you're using

• Architecture preferences - MVC, component-based, microservices, etc.

• Team structure - How your development team is organized

• Deployment requirements - Where and how your app will be deployed

Example Good Description for File Structure:

I'm building a React/Next.js web application with TypeScript, using Supabase for the backend and Tailwind CSS for styling. The app will be deployed on Vercel and needs to support both web and mobile responsive design. I prefer a component-based architecture with clear separation between UI components, business logic, and data access layers.

Troubleshooting

Common Issues

Too Few Files Generated:

• Add more detail about your technology stack and architecture

• Include specific frameworks, libraries, and tools you're using

• Try the "Generate Additional File Structure Elements" button

Structure Doesn't Match Your Preferences:

• Edit the generated structure to match your team's conventions

• Add custom folders for your specific needs

• Modify file organization to align with your architecture

Missing File Types:

• Add configuration files for your specific build tools

• Include testing files if you plan to write tests

• Add documentation files for your project

Dependencies Seem Wrong:

• Edit file relationships to match your actual architecture

• Update import/export patterns to reflect your framework

• Consider how your files will actually interact

Next Steps

After generating the file structure:

1. Review the organization to ensure it matches your preferences

2. Validate with your development team for consistency

3. Plan your development approach using the file structure as a guide

4. Set up your development environment based on the suggested structure

5. Begin implementation following the generated file organization

The file structure provides the foundation for your application's codebase organization. A well-structured codebase leads to easier maintenance, better collaboration, and more successful development outcomes.