ignitionstack.pro v1.0 is out! Read the announcement →
Skip to Content

Project Structure

Understanding the ignitionstack.pro architecture and folder organization.

Overview

Core Directories

/src/app - Next.js App Router

The main application code using Next.js 15 App Router with React 19.

src/app/
├── [locale]/                 # Internationalized routes (pt, en, es)
│   ├── (pages)/             # Public pages (grouped route)
│   │   ├── blog/            # Blog with MDX support
│   │   ├── chat/            # AI Chatbot interface
│   │   ├── contact/         # Contact form
│   │   ├── dashboard/       # User dashboard
│   │   ├── login/           # Authentication
│   │   ├── projects/        # Projects management
│   │   ├── settings/        # User settings
│   │   └── store/           # E-commerce store
│   └── admin/               # Admin panel
│       └── (protected)/     # Auth-protected admin routes
├── api/                     # API routes (webhooks, etc.)
├── auth/                    # Auth callbacks
├── components/              # React components
├── hooks/                   # Custom React hooks
├── lib/                     # Utilities and helpers
├── server/                  # Server queries/actions
└── test/                    # Unit & integration tests

The [locale] segment enables i18n routing with next-intl. All pages inside are automatically translated.

/src/app/components - UI Components

Organized by feature and reusability:

components/
├── admin/          # Admin dashboard components
├── ai/             # AI chatbot components
├── auth/           # Authentication UI
├── blog/           # Blog-related components
├── commons/        # Shared components (Header, Footer, etc.)
├── contact/        # Contact form components
├── insights/       # Analytics visualizations
├── landing-page/   # Hero, Features, Pricing, etc.
├── projects/       # Project management UI
├── store/          # E-commerce components
└── ui/             # Base UI components (Button, Input, Card, etc.)

/src/app/lib - Utilities & Business Logic

Core utilities and integrations:

lib/
├── ai/                 # AI provider integrations
├── auth/               # Authentication utilities
├── blog/               # Blog helpers
├── mappers/            # Entity mappers (DB ↔ Domain)
├── repositories/       # Data access layer
├── services/           # Business services
├── supabase/           # Supabase client factories
├── utils/              # General utilities
├── validations/        # Zod schemas & validators
├── action-result.ts    # Standardized action returns
├── admin-action-wrapper.ts  # Admin auth decorator
├── analytics.ts        # Analytics tracking
├── cache.ts            # React cache utilities
├── logger.ts           # Pino structured logging
└── stripe.ts           # Stripe integration

/src/app/server - Server Functions

Server-side data fetching and mutations:

server/
├── insights/           # Analytics queries
├── queries/            # Data queries (read operations)
└── actions/            # Mutations (create, update, delete)

Always use Server Actions for mutations. They provide better security with automatic CSRF protection.

/src/app/hooks - Custom React Hooks

Reusable hooks for common patterns:

hooks/
├── index.ts                  # Central exports
├── use-async-action.ts       # Async state management
├── use-optimistic-action.ts  # Optimistic UI updates
└── use-form-field.ts         # Form field validation

Supporting Directories

/src/i18n - Internationalization

i18n/
├── locales/
│   ├── en.json    # English translations
│   ├── pt.json    # Portuguese translations
│   └── es.json    # Spanish translations
└── config.ts      # i18n configuration

/src/store - State Management

store/
└── use-store.ts   # Zustand global store

/src/types - TypeScript Types

types/
├── supabase.ts    # Generated Supabase types
└── index.ts       # Shared type definitions

/supabase - Database

supabase/
├── migrations/    # SQL migrations
├── seed.sql       # Seed data
└── config.toml    # Supabase config

Key Files

FilePurpose
src/middleware.tsi18n routing, auth checks, rate limiting
next.config.tsNext.js configuration
tailwind.config.tsTailwind CSS customization
tsconfig.jsonTypeScript configuration
.env.exampleEnvironment variables template

Architecture Patterns

Repository Pattern

Data access is abstracted through repositories:

// lib/repositories/user-repository.ts
export const userRepository = {
  async findById(id: string) { ... },
  async create(data: CreateUserInput) { ... },
  async update(id: string, data: UpdateUserInput) { ... },
}

Entity Mappers

Transform database rows to domain objects:

// lib/mappers/product.ts
export function mapProductFromDB(row: ProductRow): Product {
  return {
    id: row.id,
    name: row.name,
    price: row.price_cents / 100,
    // ...
  }
}

Action Result Pattern

Standardized server action returns:

// lib/action-result.ts
type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string }

Admin Action Wrapper

Decorator for admin-only operations:

// Automatically validates admin auth
export const deleteUser = withAdminAuth(async (userId: string) => {
  // ...
})

Import Aliases

Use @/ for clean imports:

// Instead of:
import { Button } from '../../../components/ui/button'
 
// Use:
import { Button } from '@/components/ui/button'

Next Steps