AI Call Assistant Platform

Call Recording & Transcription Service

A robust, production-ready API service built with NestJS that enables users to record phone calls and automatically transcribe them using asynchronous background processing.

📋 Table of Contents

Overview
Features
Tech Stack
Architecture Diagram
Architecture Decisions
Getting Started
API Endpoints
Environment Variables
Docker Setup
Development
Project Structure
TODO / Future Improvements
License

🎯 Overview

This platform allows users to:

Register and authenticate using JWT-based authentication with refresh token support
Create and manage phone call records with metadata (title, duration, participants)
Automatically trigger transcription when a call is created (asynchronous background processing)
Track transcription status with real-time updates (pending → processing → completed / failed)
Retrieve transcription results with error handling and retry mechanisms

The project simulates AI transcription with:

Random processing delays (2-10 seconds)
5% random failure rate for testing retry logic
Mock transcription text generation
Exponential backoff retry strategy (3 attempts max)

✨ Features

Authentication & Authorization

✅ User registration with unique nickname validation
✅ JWT-based authentication (access + refresh tokens)
✅ Secure password hashing with bcrypt
✅ Token refresh endpoint
✅ Protected routes with AuthGuard
✅ Redis-based refresh token storage

Call Management

✅ Create new call records
✅ List calls with pagination, sorting, and filtering
✅ Search calls by title or participants
✅ Get call details by ID
✅ Update call information
✅ Delete calls (cascades to transcriptions)
✅ User ownership validation

Transcription Service

✅ Automatic transcription initiation on call creation
✅ Asynchronous background processing with BullMQ
✅ Status tracking: pending → processing → completed / failed
✅ Retry mechanism with exponential backoff (3 attempts)
✅ Error logging and handling
✅ Mock AI transcription simulation
✅ Queue job persistence and monitoring

API Documentation

✅ Swagger/OpenAPI documentation (/api)
✅ Interactive API testing interface
✅ Complete request/response schemas
✅ Error response documentation
✅ Postman / Thunder collection (share link)

Postman/Thunder collection (import):

Shared collection: https://universal-rocket-51567.postman.co/workspace/My-Workspace~c74fd85a-7e6f-40d2-8173-85982193135a/collection/27067617-a5ed3ddc-341a-49d1-983b-c49d6dc463b7?action=share&creator=27067617&active-environment=27067617-35c32dbb-9495-48d9-83e1-24c6265cd6cd
To import into Postman: File → Import → Paste Link → Import
To import into Thunder Client (VS Code): Export collection from Postman (or use the Postman link) and import JSON via Thunder Client import.

🛠 Tech Stack

Framework & Language

NestJS (v11.0.1) - Progressive Node.js framework with excellent TypeScript support, built-in dependency injection, and modular architecture
TypeScript (v5.7.3) - Type safety and improved developer experience

Database

MongoDB (via Mongoose v8.19.1) - NoSQL database chosen for:
- Flexible schema for evolving call/transcription data structures
- Excellent performance for document-based operations
- Native support for complex queries and aggregations
- Easy horizontal scaling

Caching & Queue

Redis (via ioredis v5.8.1) - Used for:
- Refresh token storage (session management)
- Future: Rate limiting and caching
BullMQ (v5.61.0) - Robust job queue for:
- Asynchronous transcription processing
- Retry mechanisms and job persistence
- Background task monitoring

Authentication

JWT (@nestjs/jwt v11.0.0) - Stateless authentication
bcryptjs (v3.0.2) - Secure password hashing

API Documentation

Swagger (@nestjs/swagger v11.2.1) - Auto-generated API documentation

Validation

class-validator (v0.14.2) - DTO validation
class-transformer (v0.5.1) - Object transformation

DevOps

Docker & Docker Compose - Containerization for consistent environments
ESLint & Prettier - Code quality and formatting

🏗 Architecture Diagram

🏗 Architecture Decisions

Why NestJS?

Modular Architecture: Clear separation of concerns with modules, services, and controllers
TypeScript-first: Full type safety and excellent IDE support
Dependency Injection: Easy testing and maintainable code
Ecosystem: Built-in support for Swagger, validation, and microservices
Production-ready: Battle-tested in enterprise applications

Why MongoDB?

Document Model: Natural fit for call records and transcription data
Flexibility: Easy to add new fields without migrations
Performance: Fast reads/writes for our use case
Scalability: Horizontal scaling support for future growth

Why BullMQ?

Reliability: Job persistence and fault tolerance
Retry Logic: Built-in exponential backoff
Monitoring: Redis-based queue dashboard support
Performance: Efficient job processing with worker pools

Why Redis?

Speed: In-memory storage for fast token validation
TTL Support: Auto-expiring refresh tokens
Queue Backend: Required for BullMQ
Future-proof: Ready for caching and rate limiting

Design Patterns Used

Repository Pattern: Data access abstraction
Service Layer Pattern: Business logic separation
DTO Pattern: Request/response validation and transformation
Guard Pattern: Authentication and authorization
Interceptor Pattern: Request/response transformation
Exception Filter Pattern: Centralized error handling

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
Docker & Docker Compose
Git

Installation

Clone the repository

git clone https://github.com/alakkaya/call-assistant-platform.git
cd call-assistant-platform

Create environment file
```
cp .env.example .env
```

Update .env with your configuration (optional - defaults work for Docker)

PORT=3000
MONGODB_URI=mongodb://mongo:27017/call-assistant-platform

# JWT Secrets (CHANGE IN PRODUCTION!)
JWT_SECRET_ACCESS=your_secure_access_secret_key_here
JWT_SECRET_REFRESH=your_secure_refresh_secret_key_here
JWT_EXPIRATION_ACCESS=1h
JWT_EXPIRATION_REFRESH=7d

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

Start with Docker Compose
```
cd docker
docker-compose up --build -d
```
Verify services are running
```
docker ps
```
You should see:
- call-assistant-platform-app (API server)
- call-assistant-platform-mongo (MongoDB)
- call-assistant-platform-redis (Redis)
Access the application
- API: http://localhost:3000
- Swagger UI: http://localhost:3000/api

📚 API Endpoints

Authentication

Method	Endpoint	Description	Auth Required
`POST`	`/auth/register`	Register new user	❌
`POST`	`/auth/login`	Login and get tokens	❌
`POST`	`/auth/logout`	Logout (invalidate refresh token)	✅
`POST`	`/auth/refresh-token`	Refresh access token	❌
`GET`	`/auth/me`	Get current user info	✅

Calls

Method	Endpoint	Description	Auth Required
`POST`	`/calls`	Create new call (auto-starts transcription)	✅
`GET`	`/calls`	List calls (with pagination, sorting, search)	✅
`GET`	`/calls/:id`	Get call details	✅
`PUT`	`/calls/:id`	Update call information	✅
`DELETE`	`/calls/:id`	Delete call (cascades to transcription)	✅

Transcription

Method	Endpoint	Description	Auth Required
`GET`	`/calls/:callId/transcription`	Get transcription status/result	✅

Example Request Flow

Detailed example requests were intentionally removed from the public README to keep documentation concise. Use the Swagger UI at /api for interactive testing and concrete request examples.

🔐 Environment Variables

This project already includes a .env.example in the repository root. Copy it to .env and update values as needed. The .env.example covers the required variables (PORT, MONGODB_URI, JWT secrets and Redis settings).

Security note: Keep secrets out of version control and rotate JWT secrets in production.

🐳 Docker Setup

Starting the Application

# Navigate to docker directory
cd docker

# Build and start all services
docker-compose up --build -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Docker Services

The docker-compose.yml defines 3 services:

call-assistant-platform-app (Node.js API)
- Port: 3000:3000
- Depends on: MongoDB, Redis
- Volume mounts source code for hot-reload
call-assistant-platform-mongo (MongoDB)
- Port: 27016:27017 (external:internal)
- Persistent data storage
call-assistant-platform-redis (Redis)
- Port: 6378:6379 (external:internal)
- Used for queues and token storage

docker restart call-assistant-platform-app docker logs -f call-assistant-platform-app docker exec -it call-assistant-platform-app sh docker exec -it call-assistant-platform-mongo mongosh docker exec -it call-assistant-platform-redis redis-cli

💻 Development

Local development steps are intentionally shortened in this README. Use the following quick commands for development and testing; more detailed guides live in the developer docs or project wiki.

# Install dependencies
npm install

# Start in development mode (requires MongoDB and Redis to be available)
npm run start:dev

# Build & run production
npm run build
npm run start:prod

# Lint & format
npm run lint
npm run format

# Testing
npm run test
npm run test:e2e
npm run test:cov

📁 Project Structure

call-assistant-platform/
├── docker/
│   ├── Dockerfile              # Node.js app container
│   └── docker-compose.yml      # Multi-container setup
├── src/
│   ├── core/                   # Shared utilities and core functionality
│   │   ├── cache/              # Redis service and cache utilities
│   │   ├── decorator/          # Custom decorators (ApiResponse, ReqUser, etc.)
│   │   ├── enum/               # Shared enums (TranscriptionStatus)
│   │   ├── error/              # Custom exceptions and error codes
│   │   ├── filter/             # Global exception filter
│   │   ├── guard/              # Authentication guard
│   │   ├── helper/             # Utility functions (mongo, mask)
│   │   ├── interceptor/        # Response transformation interceptor
│   │   └── interface/          # TypeScript interfaces
│   ├── modules/
│   │   ├── auth/               # Authentication module
│   │   │   ├── controller/     # Login, register, refresh endpoints
│   │   │   ├── dto/            # Request/response DTOs
│   │   │   └── service/        # JWT logic, token management
│   │   ├── calls/              # Call management module
│   │   │   ├── controller/     # CRUD endpoints
│   │   │   ├── dto/            # Call DTOs
│   │   │   ├── model/          # Mongoose schema
│   │   │   ├── repository/     # Data access layer
│   │   │   └── service/        # Business logic
│   │   ├── transcription/      # Transcription module
│   │   │   ├── controller/     # Get transcription endpoint
│   │   │   ├── dto/            # Transcription DTOs
│   │   │   ├── model/          # Mongoose schema
│   │   │   ├── processor/      # BullMQ job processor
│   │   │   ├── repository/     # Data access layer
│   │   │   └── service/        # Queue management, status updates
│   │   ├── user/               # User module
│   │   │   ├── dto/            # User DTOs
│   │   │   ├── model/          # Mongoose schema
│   │   │   ├── repository/     # Data access layer
│   │   │   └── service/        # User operations
│   │   └── utils/
│   │       └── bullmq/         # BullMQ configuration module
│   ├── app.module.ts           # Root application module
│   └── main.ts                 # Application entry point
├── test/                       # Test files
├── .env.example                # Environment variables template
├── .gitignore
├── nest-cli.json
├── package.json
├── README.md
├── tsconfig.json
└── tsconfig.build.json

📝 TODO / Future Improvements

High Priority

Unit Tests: Add comprehensive test coverage for services and repositories
E2E Tests: Implement end-to-end API tests with supertest
CI/CD Pipeline: Set up GitHub Actions for automated testing and deployment
Logging: Implement structured logging (Winston/Pino) with log levels
Monitoring: Add health check endpoints and metrics (Prometheus)

Performance & Scalability

Event-Driven Architecture: Replace circular dependencies with event emitters (NestJS EventEmitter)
- Decouple CallService → TranscriptionService dependency
- Use domain events: call.created, call.deleted, etc.
Database Indexing: Add indexes on frequently queried fields (userId, callId, status)
Caching Strategy: Cache frequently accessed data (user profiles, call summaries)
Rate Limiting: Implement API rate limiting to prevent abuse

Security Enhancements

Input Sanitization: Add MongoDB injection protection
CORS Configuration: Properly configure CORS for production
Helmet.js: Add security headers
API Versioning: Implement versioned API endpoints (/v1/calls)
Secrets Management: Integrate with AWS Secrets Manager or Vault
Audit Logs: Track sensitive operations (login, data modifications)

Features

Real AI Integration: Replace mock transcription with actual AI service (OpenAI Whisper, Google Speech-to-Text)
Audio File Upload: Support actual call recording file uploads (S3/MinIO storage)
Webhooks: Notify external systems when transcription completes
Search Improvements: Full-text search on transcription content (Elasticsearch)
Analytics Dashboard: User statistics, transcription success rates, average processing time
Call Tags/Categories: Add tagging system for better organization
Shared Calls: Allow users to share call transcriptions with others

Code Quality

SonarQube Integration: Static code analysis
Dependency Updates: Automated dependency update checks (Dependabot)
Performance Profiling: Add APM (Application Performance Monitoring)
Error Tracking: Integrate Sentry or similar error tracking service

📄 License

This project is MIT licensed.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

📧 Contact

For questions or support, please open an issue on GitHub.

Built with ❤️ using NestJS

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
docker		docker
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
architecture-diagram.png		architecture-diagram.png
eslint.config.mjs		eslint.config.mjs
nest-cli.json		nest-cli.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

AI Call Assistant Platform

📋 Table of Contents

🎯 Overview

✨ Features

Authentication & Authorization

Call Management

Transcription Service

API Documentation

🛠 Tech Stack

Framework & Language

Database

Caching & Queue

Authentication

API Documentation

Validation

DevOps

🏗 Architecture Diagram

🏗 Architecture Decisions

Why NestJS?

Why MongoDB?

Why BullMQ?

Why Redis?

Design Patterns Used

🚀 Getting Started

Prerequisites

Installation

📚 API Endpoints

Authentication

Calls

Transcription

Example Request Flow

🔐 Environment Variables

🐳 Docker Setup

Starting the Application

Docker Services

💻 Development

📁 Project Structure

📝 TODO / Future Improvements

High Priority

Performance & Scalability

Security Enhancements

Features

Code Quality

📄 License

🤝 Contributing

📧 Contact

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages