Project Structure

Comprehensive overview of the Earna AI Console repository organization and key files.

Repository Overview

The project consists of three independent Next.js applications:

• earna-ai
  • console
    • Main chat application (Next.js 15)
  • apps
  • docs-nextra
  • README.md
  • .gitignore

Console Application Structure

• console
  • app
    • (auth)
    • api
      • chat
      • models
      • avatar
      • tts
      • voice
    • layout.tsx
    • page.tsx
    • globals.css
  • components
    • chat
    • ui
    • avatar
    • voice
  • lib
    • ai
    • supabase
    • hooks
    • utils.ts
    • constants.ts
  • public
  • package.json
  • tsconfig.json
  • next.config.js
  • tailwind.config.ts
  • .env.example

Key Directories Explained

/app - Next.js App Router

The main application directory using Next.js 15 App Router:

• (auth)/ - Grouped authentication routes
• api/ - API route handlers for all endpoints
• layout.tsx - Root layout with providers
• page.tsx - Main chat interface page

/components - React Components

Organized by feature:

• chat/ - Chat-specific components
• ui/ - Reusable UI components (shadcn/ui)
• avatar/ - HeyGen avatar components
• voice/ - Voice/audio components

/lib - Core Libraries

Business logic and utilities:

• ai/ - AI model configurations and helpers
• supabase/ - Database client and types
• hooks/ - Custom React hooks
• utils.ts - Utility functions

Important Files

Configuration Files

• next.config.js
• tsconfig.json
• tailwind.config.ts
• package.json
• .env.example

API Routes

/app/api/chat/route.ts

// Main chat endpoint - handles streaming responses
export async function POST(req: Request) {
  const { messages, model } = await req.json();
  // Stream AI response
}

/app/api/models/route.ts

// List available models and their status
export async function GET() {
  return Response.json(availableModels);
}

Component Structure

/components/chat/chat-interface.tsx

// Main chat UI component
export function ChatInterface() {
  // Manages conversation state
  // Handles message sending
  // Renders message list
}

/lib/ai/models.ts

// Model configuration and management
export function getModel(modelId: string) {
  // Returns configured AI model
}

File Naming Conventions

Components

• PascalCase: ChatInterface.tsx, MessageList.tsx
• Suffix with type: .tsx for components, .ts for utilities
• Index files: Use index.ts for barrel exports

API Routes

• Lowercase: route.ts for App Router
• Dynamic routes: [id]/route.ts for parameters
• Nested structure: Mirror URL structure

Utilities

• camelCase: useChat.ts, formatMessage.ts
• Descriptive names: generateChatTitle.ts
• Group by feature: /lib/ai/, /lib/supabase/

Environment Files

.env.example     # Template with all variables
.env.local       # Local development (gitignored)
.env.production  # Production values (gitignored)
.env.test        # Test environment

Build Output

• .next
• node_modules
• out

Database Structure

Located in Supabase, not in repository:

-- Main tables
users
conversations
messages
files
 
-- Functions
generate_chat_title()
check_message_limit()
 
-- RLS Policies
users_own_conversations
users_own_messages

Documentation Structure

• docs-nextra/src/content
  • index.mdx
  • get-started.mdx
  • core-features
  • architecture-docs

Scripts Reference

Development

{
  "dev": "next dev",
  "build": "next build",
  "start": "next start"
}

Type Checking

{
  "type-check": "tsc --noEmit",
  "lint": "next lint",
  "format": "prettier --write ."
}

Database

{
  "generate:types": "supabase gen types",
  "db:migrate": "supabase db push"
}

Adding New Features

1. New API Endpoint

1. Create route in /app/api/[feature]/route.ts
2. Add types to /lib/types/[feature].ts
3. Create hook in /lib/hooks/use-[feature].ts

2. New UI Component

1. Create component in /components/[feature]/
2. Add to barrel export in /components/[feature]/index.ts
3. Import using @/components/[feature]

3. New AI Model

1. Add configuration to /lib/ai/models.ts
2. Update environment variables
3. Add to model selector UI

Best Practices

1. Keep API routes thin - Business logic in /lib
2. Use Server Components - Where possible for performance
3. Colocate related files - Feature-based organization
4. Type everything - Full TypeScript coverage
5. Document complex logic - Inline comments for clarity