Tomodachi AI API

Build and chat with your personalized AI companion - Voice calls included!

Live Demo · API Documentation · Report Bug

📖 Table of Contents

• Tomodachi AI API
  • 📖 Table of Contents
  • 🌟 Features
  • 🚀 Tech Stack
  • 📋 Prerequisites
  • 🚀 Getting Started
  • 🐳 Docker Setup
    • Development Environment
    • Production Environment
    • Services & Ports
  • 📚 API Documentation
    • Authentication
    • Companions
    • Chat & Voice
  • 💻 Development
    • Local Setup
    • File Structure
  • 🧪 Testing
  • 📦 Deployment
    • Render
    • Docker (Production)
  • 🤝 Contributing
  • 📝 License
  • 👥 Contact
  • 🙏 Acknowledgments

🌟 Features

• 🤖 Custom AI Companions
  • Create personalized AI companions with unique personalities
  • Choose from various roles (Assistant, Friend, Partner)
  • Customize appearance and voice
• 💬 Advanced Chat Features
  • Real-time messaging with WebSocket support
  • Message history tracking
  • Smart context management
• 🎙️ Voice Integration
  • Text-to-Speech using ElevenLabs
  • Natural voice conversations
  • Multiple voice options
• 🔒 Security
  • JWT-based authentication
  • Role-based access control
  • Secure API endpoints
• ⚡ High Performance
  • Built with Bun runtime
  • Redis caching
  • PostgreSQL for data persistence

🚀 Tech Stack

• Runtime & Framework
  • Bun - Ultra-fast JavaScript runtime
  • Hono - Lightweight web framework
  • TypeScript - Type-safe code
• Database & Caching
  • PostgreSQL - Primary database
  • Redis - Caching and queue management
  • Prisma - ORM
• AI Services
  • OpenAI - Chat completions (GPT-4)
  • ElevenLabs - Voice synthesis
• DevOps
  • Docker - Containerization
  • Docker Compose - Multi-container management

📋 Prerequisites

• Docker >= 24.0.0
• Docker Compose >= 2.21.0
• Bun >= 1.0.0 (for local development)
• OpenAI API Key
• ElevenLabs API Key

🚀 Getting Started

1. Clone the repository

git clone https://github.com/zidanhafiz/TomodachiAI-API.git
cd TomodachiAI-API

2. Set up environment variables

cp .env.example .env

3. Configure environment variables

# Application
PORT=3000
FRONTEND_URL=http://localhost:3000

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=tomodachi
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/tomodachi
DOCKER_DATABASE_URL=postgresql://postgres:postgres@db:5432/tomodachi

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# JWT
JWT_SECRET=your_jwt_secret

# AI Services
OPENAI_API_KEY=your_openai_api_key
ELEVENLABS_API_KEY=your_elevenlabs_api_key

🐳 Docker Setup

Development Environment

# Start development services
docker compose -f compose.dev.yml up -d

# View logs
docker compose -f compose.dev.yml logs -f

# Stop services
docker compose -f compose.dev.yml down

Production Environment

# Build and start production services
docker compose -f compose.prod.yml up -d --build

# View logs
docker compose -f compose.prod.yml logs -f

# Stop services
docker compose -f compose.prod.yml down

Services & Ports

• API
  • Development: http://localhost:4000
  • Production: http://localhost:3000
• PostgreSQL: localhost:5432
• Redis: localhost:6379
• RedisInsight (Dev only): http://localhost:8001

📚 API Documentation

Authentication

POST /api/auth/register
POST /api/auth/login
POST /api/auth/refresh

Companions

POST /api/agents/create
GET /api/agents
GET /api/agents/:id
PATCH /api/agents/:id
DELETE /api/agents/:id

Chat & Voice

POST /api/chat/message
GET /api/chat/history
POST /api/voice/synthesize

Detailed API documentation available at /v1/api-docs when running the server.

💻 Development

Local Setup

# Install dependencies
bun install

# Generate Prisma client
bunx prisma generate

# Run database migrations
bunx prisma migrate dev

# Start development server
bun run dev

File Structure

src/
├── models/     # Database models
├── routes/     # API routes
├── middlewares/# Custom middlewares
├── utils/      # Utility functions
└── workers/    # Background workers

🧪 Testing

# Run all tests
bun test

# Run specific test file
bun test test/api/users.test.ts

📦 Deployment

Render

Docker (Production)

1. Build the image:

docker compose -f compose.prod.yml build

2. Deploy:

docker compose -f compose.prod.yml up -d

🤝 Contributing

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contact

Instagram - @hafizrofiyani

🙏 Acknowledgments

• Bun
• Hono
• OpenAI
• ElevenLabs