Skip to main content

​
Overview

Voxora uses a monorepo architecture managed with npm workspaces and Turborepo. This allows for efficient code sharing, consistent tooling, and simplified dependency management across multiple applications and packages.

​
Directory Structure

voxora/
├── apps/
│   ├── web/              # Next.js frontend application
│   └── api/              # Express backend server
├── packages/
│   ├── eslint-config/    # Shared ESLint configuration
│   └── typescript-config/ # Shared TypeScript configuration
├── docker/
│   └── docker-compose.dev.yml # Local development services
├── .github/
│   └── workflows/        # CI/CD workflows
├── .vscode/
│   └── settings.json     # VS Code workspace settings
├── turbo.json           # Turborepo configuration
├── package.json         # Root package.json
└── Makefile            # Build automation

​
Apps Directory

​
apps/web

The Next.js frontend application that provides the main user interface. 
apps/web/
├── app/                 # Next.js App Router
│   ├── (auth)/         # Authentication routes
│   ├── (dashboard)/    # Dashboard routes
│   ├── api/            # API routes
│   └── layout.tsx      # Root layout
├── components/         # React components
│   ├── ui/            # UI primitives
│   └── features/      # Feature-specific components
├── lib/               # Utility functions
├── public/            # Static assets
├── styles/            # Global styles
├── .env.development   # Development environment template
├── next.config.js     # Next.js configuration
├── tailwind.config.js # Tailwind CSS configuration
└── package.json
Key Technologies:
  • Next.js 15 (App Router)
  • React 19
  • Tailwind CSS
  • TypeScript
  • Socket.IO Client

​
apps/api

The Express backend server handling API requests and WebSocket connections. 
apps/api/
├── src/
│   ├── controllers/    # Request handlers
│   ├── models/        # Mongoose schemas
│   ├── routes/        # API routes
│   ├── services/      # Business logic
│   ├── middleware/    # Express middleware
│   ├── socket/        # Socket.IO handlers
│   ├── utils/         # Helper functions
│   ├── config/        # Configuration files
│   └── index.js       # Entry point
├── public/
│   ├── widget/        # Chat widget files
│   └── widget-loader.js
├── .env.development   # Development environment template
└── package.json
Key Technologies:
  • Express 5
  • Socket.IO
  • MongoDB (Mongoose)
  • Redis
  • JWT Authentication

​
Packages Directory

Shared packages used across multiple applications.

​
packages/eslint-config

Shared ESLint Configuration

Consistent linting rules across all apps and packages
// Usage in apps
{
  "extends": ["@voxora/eslint-config"]
}

​
packages/typescript-config

Shared TypeScript Configuration

Base TypeScript configuration for type safety
// Usage in apps
{
  "extends": "@voxora/typescript-config/nextjs.json"
}

​
Docker Services

The docker/ directory contains Docker Compose configurations for local development.
docker-compose.dev.yml
services:
  mongodb:
    image: mongo:latest
    ports: ["27017:27017"]
    
  redis:
    image: redis:alpine
    ports: ["6379:6379"]
    
  mongo-express:
    image: mongo-express:latest
    ports: ["8081:8081"]
    
  mailhog:
    image: mailhog/mailhog
    ports: ["1025:1025", "8025:8025"]

​
Configuration Files

​
turbo.json

Defines build pipeline and caching strategy for Turborepo. 
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": []
    }
  }
}

​
Root package.json

Defines workspace scripts and dependencies. 
{
  "name": "voxora",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "dev": "turbo run dev",
    "dev:full": "npm run docker:start && turbo run dev",
    "build": "turbo run build",
    "docker:start": "docker-compose -f docker/docker-compose.dev.yml up -d",
    "docker:stop": "docker-compose -f docker/docker-compose.dev.yml down"
  }
}

​
Workspace Management

​
Adding Dependencies

npm install -w root <package-name>

​
Running Scripts

npm run dev

​
Benefits of Monorepo

Code Sharing

Share configurations, utilities, and types across apps

Consistent Tooling

Single set of linting, formatting, and build tools

Atomic Changes

Update multiple apps in a single commit

Simplified CI/CD

Build and test all apps together

​
Best Practices

​
1. Dependency Management

Install shared dependencies at the root level when possible to reduce duplication.
# Good: Install at root
npm install -w root typescript

# Only when needed: Install per workspace
npm install -w apps/web next

​
2. Shared Code

Create shared packages for code used in multiple apps instead of duplicating.
packages/
└── shared-types/
    ├── index.ts
    └── package.json

​
3. Build Order

Turborepo automatically handles build dependencies. Define them in turbo.json: 
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"]  // Build dependencies first
    }
  }
}

​
Development Workflow

1

Install Dependencies

npm install
2

Start Docker Services

npm run docker:start
3

Start Development Servers

npm run dev
4

Make Changes

Edit files in any workspace
5

Build for Production

npm run build

​
Next Steps

Architecture

Understand the system architecture

Development Setup

Set up your development environment

Scripts Reference

Learn about available npm scripts

Contributing

Contributing guidelines