Architecture

Featured

Our Full-Stack Monorepo Architecture in 2026

A practical guide to how we structure our multi-platform projects — from shared TypeScript types to Docker orchestration — across React, React Native, Electron, and Node.js.

🧑‍💻

Harsha Bonthada

Founder & Lead Engineer

February 1, 2026

8 min read

Why Monorepo?

When you're building products that span Web, Mobile, Desktop, and Backend — all sharing business logic, types, and utilities — a monorepo isn't just convenient. It's essential.

At Circuvent, our larger projects (NEXUS AI OS, Financial Analyzer, TimeCapsule) all follow a monorepo structure. Here's how we organize them.

Directory Structure

project-root/
├── packages/
│   ├── shared/          # Shared types, utils, constants
│   ├── ui/              # Shared React components
│   └── api-client/      # Generated API client
├── apps/
│   ├── web/             # Next.js web app
│   ├── mobile/          # React Native / Expo
│   ├── desktop/         # Electron app
│   └── api/             # FastAPI / Express backend
├── infra/
│   ├── docker/          # Dockerfiles
│   ├── scripts/         # Build & deploy scripts
│   └── ci/              # GitHub Actions workflows
├── docs/                # Architecture docs
├── docker-compose.yml
├── package.json         # Root workspace config
└── turbo.json           # Turborepo config

Shared Type Safety

The packages/shared directory contains TypeScript interfaces that are used across all platforms:

typescript

// packages/shared/src/types/user.ts
export interface User {
  id: string;
  email: string;
  displayName: string;
  avatar?: string;
  role: 'admin' | 'user' | 'premium';
  preferences: UserPreferences;
  createdAt: Date;
  updatedAt: Date;
}

export interface UserPreferences {
  theme: 'light' | 'dark' | 'system';
  notifications: boolean;
  language: string;
  timezone: string;
}

Both the React web app and React Native mobile app import from the same package:

typescript

import type { User, UserPreferences } from '@project/shared';

This eliminates type drift between platforms — a change to the User interface immediately shows type errors everywhere it's used.

API Client Generation

We auto-generate API clients from our FastAPI OpenAPI schema:

bash

# Generate TypeScript client from FastAPI OpenAPI spec
openapi-generator-cli generate \
  -i http://localhost:8000/openapi.json \
  -g typescript-fetch \
  -o packages/api-client/src \
  --additional-properties=supportsES6=true

Docker Orchestration

Every service runs in Docker, orchestrated by docker-compose:

yaml

version: '3.8'
services:
  api:
    build: ./apps/api
    ports: ["8000:8000"]
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/app
    depends_on: [db, redis]
    
  web:
    build: ./apps/web
    ports: ["3000:3000"]
    depends_on: [api]
    
  db:
    image: postgres:16-alpine
    volumes: ["pgdata:/var/lib/postgresql/data"]
    
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

volumes:
  pgdata:

CI/CD Pipeline

Our GitHub Actions pipeline:

Lint & Type Check — ESLint + TypeScript across all packages

Unit Tests — Jest for shared packages, Pytest for backend

Build — Turborepo parallel builds

Docker Build — Multi-stage Docker images

Deploy — Push to container registry, deploy via SSH

Results

This architecture has allowed us to:

Ship features across 3 platforms simultaneously

Maintain 100% type safety from API to UI

Deploy with a single docker-compose up command

Onboard new developers in hours, not days

Tags:

Monorepo

TypeScript

Docker

CI/CD

Architecture

AI & ML

12 min read

Building NEXUS AI OS: Architecture of a 13-Agent Local AI System

Deep dive into the architecture behind NEXUS AI OS — how we orchestrate 13+ specialized AI agents running entirely on-device with Ollama, ChromaDB, and a custom IPC bus.

Ollama

Multi-Agent

🧑‍💻

Harsha Bonthada

Mar 1, 2026

DevOps

7 min read

Docker Compose for Production: Lessons from Deploying 8 Apps

Real-world lessons from running 8 production applications on Docker Compose — from health checks to zero-downtime deployments.

Harsha Bonthada

Jan 10, 2026

IoT

10 min read

ESP32 + MQTT: Building Smart Home Infrastructure at Scale

How we scaled our home automation from a single ESP32 relay to a production-grade IoT ecosystem with 9+ devices, MQTT mesh networking, and OTA firmware updates.

Harsha Bonthada

Feb 15, 2026

Stay in the Loop

Get engineering insights, project updates, and open source news delivered to your inbox.

No spam. Unsubscribe at any time. Read our Privacy Policy.

Back to Blog

Architecture

Featured

Our Full-Stack Monorepo Architecture in 2026

A practical guide to how we structure our multi-platform projects — from shared TypeScript types to Docker orchestration — across React, React Native, Electron, and Node.js.

🧑‍💻

Harsha Bonthada

Founder & Lead Engineer

February 1, 2026

8 min read

Why Monorepo?

When you're building products that span Web, Mobile, Desktop, and Backend — all sharing business logic, types, and utilities — a monorepo isn't just convenient. It's essential.

At Circuvent, our larger projects (NEXUS AI OS, Financial Analyzer, TimeCapsule) all follow a monorepo structure. Here's how we organize them.

Directory Structure

project-root/
├── packages/
│   ├── shared/          # Shared types, utils, constants
│   ├── ui/              # Shared React components
│   └── api-client/      # Generated API client
├── apps/
│   ├── web/             # Next.js web app
│   ├── mobile/          # React Native / Expo
│   ├── desktop/         # Electron app
│   └── api/             # FastAPI / Express backend
├── infra/
│   ├── docker/          # Dockerfiles
│   ├── scripts/         # Build & deploy scripts
│   └── ci/              # GitHub Actions workflows
├── docs/                # Architecture docs
├── docker-compose.yml
├── package.json         # Root workspace config
└── turbo.json           # Turborepo config

Shared Type Safety

The packages/shared directory contains TypeScript interfaces that are used across all platforms:

typescript

// packages/shared/src/types/user.ts
export interface User {
  id: string;
  email: string;
  displayName: string;
  avatar?: string;
  role: 'admin' | 'user' | 'premium';
  preferences: UserPreferences;
  createdAt: Date;
  updatedAt: Date;
}

export interface UserPreferences {
  theme: 'light' | 'dark' | 'system';
  notifications: boolean;
  language: string;
  timezone: string;
}

Both the React web app and React Native mobile app import from the same package:

typescript

import type { User, UserPreferences } from '@project/shared';

This eliminates type drift between platforms — a change to the User interface immediately shows type errors everywhere it's used.

API Client Generation

We auto-generate API clients from our FastAPI OpenAPI schema:

bash

# Generate TypeScript client from FastAPI OpenAPI spec
openapi-generator-cli generate \
  -i http://localhost:8000/openapi.json \
  -g typescript-fetch \
  -o packages/api-client/src \
  --additional-properties=supportsES6=true

Docker Orchestration

Every service runs in Docker, orchestrated by docker-compose:

yaml

version: '3.8'
services:
  api:
    build: ./apps/api
    ports: ["8000:8000"]
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/app
    depends_on: [db, redis]
    
  web:
    build: ./apps/web
    ports: ["3000:3000"]
    depends_on: [api]
    
  db:
    image: postgres:16-alpine
    volumes: ["pgdata:/var/lib/postgresql/data"]
    
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

volumes:
  pgdata:

CI/CD Pipeline

Our GitHub Actions pipeline:

Lint & Type Check — ESLint + TypeScript across all packages

Unit Tests — Jest for shared packages, Pytest for backend

Build — Turborepo parallel builds

Docker Build — Multi-stage Docker images

Deploy — Push to container registry, deploy via SSH

Results

This architecture has allowed us to:

Ship features across 3 platforms simultaneously

Maintain 100% type safety from API to UI

Deploy with a single docker-compose up command

Onboard new developers in hours, not days

Tags:

Monorepo

TypeScript

Docker

CI/CD

Architecture

AI & ML

12 min read

Building NEXUS AI OS: Architecture of a 13-Agent Local AI System

Deep dive into the architecture behind NEXUS AI OS — how we orchestrate 13+ specialized AI agents running entirely on-device with Ollama, ChromaDB, and a custom IPC bus.

Ollama

Multi-Agent

🧑‍💻

Harsha Bonthada

Mar 1, 2026

DevOps

7 min read

Docker Compose for Production: Lessons from Deploying 8 Apps

Real-world lessons from running 8 production applications on Docker Compose — from health checks to zero-downtime deployments.

Harsha Bonthada

Jan 10, 2026

IoT

10 min read

ESP32 + MQTT: Building Smart Home Infrastructure at Scale

How we scaled our home automation from a single ESP32 relay to a production-grade IoT ecosystem with 9+ devices, MQTT mesh networking, and OTA firmware updates.

Harsha Bonthada

Feb 15, 2026

Stay in the Loop

Get engineering insights, project updates, and open source news delivered to your inbox.

No spam. Unsubscribe at any time. Read our Privacy Policy.

Our Full-Stack Monorepo Architecture in 2026

Why Monorepo?

Directory Structure

Shared Type Safety

API Client Generation

Docker Orchestration

CI/CD Pipeline

Results

Related Articles

Building NEXUS AI OS: Architecture of a 13-Agent Local AI System

Docker Compose for Production: Lessons from Deploying 8 Apps

ESP32 + MQTT: Building Smart Home Infrastructure at Scale

Stay in the Loop

Our Full-Stack Monorepo Architecture in 2026

Why Monorepo?

Directory Structure

Shared Type Safety

API Client Generation

Docker Orchestration

CI/CD Pipeline

Results

Related Articles

Building NEXUS AI OS: Architecture of a 13-Agent Local AI System

Docker Compose for Production: Lessons from Deploying 8 Apps

ESP32 + MQTT: Building Smart Home Infrastructure at Scale

Stay in the Loop