Project Structure

Understanding the directory layout helps you navigate the codebase and know where to add new functionality.

Top-Level Structure

Vertical-Template/
├── src/                    # Application source code
├── packages/               # Internal packages
│   └── client/            # @enterpriseaigroup/client package
├── docs/                   # Documentation (you are here)
├── docs-site/             # Docusaurus configuration
├── public/                # Static assets
├── .claude/               # AI context and skills
└── .github/               # GitHub Actions workflows

Source Directory (src/)

src/
├── app/                           # Next.js App Router
│   ├── api/                       # API route handlers
│   │   ├── auth/[...nextauth]/   # Auth.js endpoints
│   │   │   └── route.ts          # OAuth callbacks
│   │   ├── eai/[[...rest]]/      # Catch-all API proxy
│   │   │   └── route.ts          # Proxies to backend
│   │   └── eai/config/           # Runtime config
│   │       └── route.ts          # Returns tenant config
│   ├── (presentation)/           # UI pages (route group)
│   │   └── page.tsx              # Main page
│   ├── layout.tsx                # Root layout
│   └── page.tsx                  # Landing page
│
├── eai.config/                   # Config-driven architecture
│   ├── index.ts                  # Config registry
│   ├── types.ts                  # TypeScript types
│   └── tenants/                  # Tenant configurations
│       ├── template.config.ts    # Example tenant
│       └── [tenant].config.ts    # Your tenant configs
│
├── components/                   # React components
│   └── ui/                       # Shadcn UI components
│       ├── button.tsx
│       ├── input.tsx
│       └── ...
│
├── lib/                          # Shared utilities
│   ├── utils.ts                  # General utilities
│   └── ...
│
├── auth.ts                       # Auth.js configuration
└── middleware.ts                 # Route protection middleware

Key Files Explained

Configuration Files

File	Purpose
src/eai.config/index.ts	Exports getTenantConfig(tenantId)
src/eai.config/types.ts	TypeScript types for EAIConfig
src/eai.config/tenants/*.config.ts	Individual tenant configurations

API Routes

Route	Purpose
/api/auth/[...nextauth]	Auth.js OAuth endpoints
/api/eai/[[...rest]]	Catch-all proxy to backend
/api/eai/config	Returns runtime tenant config

Core Files

File	Purpose
src/auth.ts	Auth.js provider configuration
src/middleware.ts	Route protection and redirects
src/app/layout.tsx	Root layout with providers

Client Package (packages/client/)

packages/client/
└── src/
    ├── config/                    # Configuration system
    │   ├── EAIConfigProvider.tsx  # React context provider
    │   ├── createGlobalStore.ts   # Zustand store factory
    │   ├── SlotRenderer.tsx       # Component slot renderer
    │   └── ComponentRegistry.ts   # Component name → React component map
    │
    ├── components/                # Shared UI components
    │   ├── Header/
    │   ├── Sidebar/
    │   └── ...
    │
    ├── hooks/                     # Custom React hooks
    │   ├── useStoreValue.ts       # Read from store
    │   ├── useSetStore.ts         # Write to store
    │   └── ...
    │
    └── index.ts                   # Package exports

Documentation (docs/)

docs/
├── getting-started/              # Onboarding guides
│   ├── quickstart.md
│   ├── prerequisites.md
│   ├── first-vertical.md
│   └── onboarding.md
│
├── architecture/                 # System design
│   ├── overview.md
│   ├── project-structure.md      # This file
│   ├── data-flow.md
│   └── decisions/               # Architecture Decision Records
│       ├── ADR-001-config-driven.md
│       └── ...
│
├── configuration/               # Config reference
│   ├── overview.md
│   ├── tenant-config.md
│   └── examples/
│
├── extending/                   # Extension guides
│   ├── adding-pages.md
│   ├── adding-api-routes.md
│   └── custom-components.md
│
└── reference/                   # API reference
    ├── hooks.md
    └── components.md

Where to Add Things

I want to...	Location
Add a new page	src/app/(presentation)/[page-name]/page.tsx
Add a new API route	src/app/api/[route-name]/route.ts
Add a UI component	src/components/ or packages/client/src/components/
Create a new tenant	src/eai.config/tenants/[tenant].config.ts
Add a utility function	src/lib/
Add documentation	docs/[category]/

Import Aliases

The project uses TypeScript path aliases:

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

// Client package
import { useStoreValue } from '@enterpriseaigroup/client';

Configured in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Related Documentation

• Architecture Overview - System design
• Adding Pages - Create new pages
• Configuration Overview - Tenant configuration