Prerequisites
Before you begin, ensure you have the following installed on your machine:
- Node.js 20.x or higher
- Package Manager: One of the following:
- Bun (recommended)
- npm (comes with Node.js)
- pnpm
- Git for version control
- Supabase CLI for database management
This project uses Next.js 15 with the App Router and TypeScript. Familiarity with these technologies is recommended.
Clone the Repository
First, clone the repository to your local machine:
git clone <repository-url>
cd echoes-of-the-past
Install Dependencies
Install the project dependencies using your preferred package manager:
The project includes the following key dependencies:
- Frontend Framework: Next.js 15.3.2, React 19
- Database: Supabase (@supabase/supabase-js, @supabase/ssr)
- Voice AI: Vapi AI SDK (@vapi-ai/web)
- Text-to-Speech: ElevenLabs (@elevenlabs/elevenlabs-js)
- AI Models: OpenAI SDK
- State Management: TanStack Query (React Query)
- Caching: Upstash Redis
- UI Components: Radix UI, Tailwind CSS
- Forms: React Hook Form with Zod validation
Project Structure
Understand the codebase organization:
echoes-of-the-past/
├── app/ # Next.js App Router
│ ├── (other)/ # Auth routes (sign-in, sign-up, callback)
│ ├── app/ # Main application routes
│ │ ├── analytics/ # User analytics dashboard
│ │ ├── call/[id]/ # Voice call interface
│ │ ├── new/ # Create new conversation
│ │ ├── quizzes/ # Quiz system
│ │ └── page.tsx # Main app page
│ ├── layout.tsx # Root layout
│ └── page.tsx # Landing page
├── components/ # Reusable UI components
│ ├── ui/ # Base UI components (shadcn/ui)
│ └── ... # Custom components
├── features/ # Feature-based modules
│ ├── analytics/ # Analytics features
│ ├── auth/ # Authentication
│ ├── call/ # Voice call functionality
│ ├── character/ # Historical figure management
│ ├── dashboard/ # Dashboard features
│ ├── quiz/ # Quiz system
│ └── sidebar/ # Navigation sidebar
├── lib/ # Core library code
│ ├── ai.ts # OpenAI client configuration
│ ├── vapi.ts # Vapi AI client
│ ├── elevenlabs.ts # ElevenLabs client
│ ├── redis.ts # Redis client
│ ├── prompt.ts # AI prompt templates
│ └── utils.ts # Utility functions
├── utils/ # Utility modules
│ └── supabase/ # Supabase client utilities
│ ├── client.ts # Browser client
│ ├── server.ts # Server client
│ └── middleware.ts # Auth middleware
├── supabase/ # Database configuration
│ └── migrations/ # SQL migrations
├── database.types.ts # Generated TypeScript types
├── middleware.ts # Next.js middleware
└── package.json # Dependencies and scripts
Running the Development Server
After installing dependencies and setting up your environment variables (see Environment Setup), start the development server:
The development server will start with Turbopack enabled for faster builds:
▲ Next.js 15.3.2
- Local: http://localhost:3000
- Turbopack: enabled
✓ Ready in 1.2s
Available Scripts
The following scripts are available in package.json:
| Script | Command | Description |
|---|
dev | next dev --turbopack | Start development server with Turbopack |
build | next build | Build production bundle |
start | next start | Start production server |
lint | next lint | Run ESLint |
format | prettier --write . | Format code with Prettier |
gen-types | npx supabase gen types... | Generate TypeScript types from Supabase |
Next Steps
Configure Environment Variables
Set Up Database
Initialize your Supabase project and run migrations. See Database Setup. Start Building
You’re ready to start developing! Explore the codebase and make your first changes.
Development Tips
- The project uses Turbopack for faster development builds
- TypeScript strict mode is enabled for type safety
- ESLint and Prettier are configured for code quality
- Use TanStack Query DevTools to debug data fetching
Troubleshooting
Port Already in Use
If port 3000 is already in use, you can specify a different port:
Type Errors
If you encounter TypeScript errors related to database types, regenerate them:
Module Not Found
Clear your package manager’s cache and reinstall:
rm -rf node_modules bun.lockb
bun install