Bernhard the Builder
AboutAppsBlogNewsDDDD

The Big Rig| Notes

The Big Rig Deployment

How I set up my local development framework for AI agent orchestration and building with an AI colony

The Big Rig Deployment
Guide
buildingFramework & Architecture
Bernhard Rieder
2026-01-12
7 MIN READ
Download Resources
AI Directive

Big Rig Deployment: When Inconsistency Drives You Mad

I'm building with an AI colony. Multiple agents working on the same codebase. Multiple projects sharing components.
Multiple services that need to talk to each other.
The problem? Every time I start a new project, I'm reinventing the wheel. Different directory structures.
Different build setups. Different port configurations. AI agents get confused.
I get confused. Nothing is consistent.
My blood pressure spiked every time I onboarded a new agent into a different project structure. So I built The Big Rig - my standard framework for every local development project.
It's not just a tech stack. It's a complete architecture designed specifically for AI agent orchestration. When an AI agent needs to understand my project structure, it's always the same.
When I need to add a new service, the pattern is already there. When I want to sell or extract a project, the structure supports it.
The Face: Next.js (App Router) + React (Port 3000).
The Backbone: Turborepo (The Ferrari of Build Systems).
The Brain: Firebase Vector Database for semantic AI memory.
This architecture works because it's predictable. AI agents can navigate it. I can navigate it.
Everything has a place, and every place has a purpose.
The Big Rig Architecture
The Big Rig: Your Digital Architecture Foundation
Why This Structure //
I chose this architecture because it's ideal for AI agent orchestration. The clear separation of concerns, the predictable directory structure, and the integrated vector database system all make it easier for AI agents to understand and work with the codebase. When building with an AI colony, consistency is everything.
TurborepoNext.jsFirebaseAI Agents

The Rigid Core, Flexible Edge Model

Before diving into the structure, it's critical to understand the distinction between System Stability (the Core) and Functional Extensibility (the Modules).
"Rigid" refers only to the infrastructure environment-the Engine. This includes:
  • Turborepo configuration - The build orchestration layer
  • Directory structure - apps/, packages/, workspace layout
  • Firebase schema & vector database - Data integrity and AI memory
  • Port 3000 - The frontend anchor
  • MCP integration - How agents connect to the system
This is the Stable Foundation. It must not change so that data remains valid, builds remain predictable, and AI agents can rely on it.
The benefit: By making the core rigid, it creates a safe harbor for the Flexible Modules. Because the core is predictable, developers can build highly adaptive packages, plugins, scrapers, and dashboards (the "Edge") without worrying that the underlying system will break.
Rigidity Is a Feature, Not a Limitation //
The rigidity of the core is the very thing that enables the flexibility of the modules. Without a rigid core, the flexible features would have nothing stable to plug into. The Engine stays fixed; the Edge evolves.
Stable Foundation + Plug-in Layer:
text
1┌─────────────────────────────────────────────────────────────┐
2│  FLEXIBLE EDGE (Modules)                                    │
3│  content-engine · newsletter · agent-chat-history · plugins  │
4│  scrapers · dashboards · future tools (02–14)                │
5├─────────────────────────────────────────────────────────────┤
6│  PLUG-IN LAYER                                               │
7│  packages/ui · packages/brain                                │
8├─────────────────────────────────────────────────────────────┤
9│  STABLE FOUNDATION (The Engine)                              │
10│  Turborepo · Next.js (3000) · Firebase · MCP · Directory     │
11└─────────────────────────────────────────────────────────────┘

The Architecture I Use

This is the structure I follow for every project. No exceptions. No variations.
Consistency is the point.
text
1THE-BIG-RIG/
2├── .git/                             # Version Control
3├── turbo.json                        # Turborepo Config
4├── apps/
5│   └── app-01-framework/             # [FRONTEND] Next.js (Port 3000)
6│       ├── next.config.js            # Configured for scalability
7│       ├── package.json              # Deps: React, Tailwind, Firebase Client SDK
8│       └── vercel.json               # Deployment Config
9│
10└── packages/                         # [FLEXIBLE EDGE] Plug-in layer
11    ├── ui/                           # Shared UI (Tailwind/Shadcn) - @repo/ui
12    ├── brain/                        # [MCP] Model Context Protocol Definitions
13    ├── content-engine/               # Content parsing & utilities - @repo/content-engine
14    ├── newsletter/                  # Subscriber Vault, email capture - @repo/newsletter
15    └── agent-chat-history/          # AI agent chat history SDK - @repo/agent-chat-history
Core packages (always present): ui, brain.
Extensible packages (add as needed): content-engine, newsletter, agent-chat-history, and future tools (Content Brain, SEO Auditor, Database Dashboard, Subscriber Vault, Semantic Linker, Social Promoter, Keyword Vault, Search Master, Ads Manager, Insights Dashboard, and more).
Every directory has a purpose. Every file has a role. AI agents can read this structure and understand it immediately.
That's the point.
The Big Rig Framework Structure
The Big Rig Framework Structure
Monorepoapps/packages/
>
The architecture is the blueprint. The directory structure is the foundation. When AI agents can predict where things live, they can work faster and make fewer mistakes.

Big Rig Deployment: How I Deploy It

The Big Rig Deployment Process
The Big Rig Deployment Process
Here's my linear execution plan. I follow this every time I initialize a new project. It works because it's explicit.
No assumptions. No shortcuts.

Step 1: Ground Zero & Backbone (Turborepo)

I start with the foundation. Turborepo is the build system that orchestrates everything. Without it, I'm managing multiple build processes manually.
That's a nightmare.
What I do:
  1. Initialize Git repository
  2. Initialize Turborepo workspace with pnpm
  3. Create pnpm-workspace.yaml with packages pointing to apps/* and packages/*
  4. Install Turborepo as a dev dependency
  5. Create turbo.json with build pipeline configuration (build depends on dependencies, outputs .next/** and dist/**, dev cache disabled)
Why this works: Turborepo handles the build orchestration. AI agents can run pnpm turbo build and everything builds in the right order.
No confusion. No manual coordination.

Step 2: Construct "The Face" (Next.js)

The frontend lives on port 3000. Always. This is the user-facing layer.
React, Tailwind, Firebase client SDK. Standard stuff, configured for high-performance delivery.
What I do:
  1. Create apps/app-01-framework directory
  2. Initialize Next.js project with App Router, TypeScript, ESLint, and Tailwind CSS
  3. Install core dependencies: react, react-dom, framer-motion, firebase, lucide-react
  4. Configure standard routing and layout patterns
  5. Create vercel.json with build command pointing to Turborepo filter
Why this works: The monorepo configuration means the frontend and shared logic communicate seamlessly. AI agents don't have to figure out complex setups. It just works.

Step 3: Construct "The Brain" (Vector AI Setup)

This is where it gets interesting. I use Firebase as my unified vector database for both development and production. This is critical for AI agent memory.
What I do:
  1. Vector DB (Firebase):
    • Create firebase.json in the root with Firestore rules and indexes configuration
    • Set GOOGLE_APPLICATION_CREDENTIALS environment variable for Firebase Admin authentication
    • Create vector database interfaces (Store and Query methods) and Result types
Why this works: AI agents need memory. They need to remember context, decisions, and patterns.
Using Firebase for vector storage provides consistency between local development and production. The interface means I can swap or extend implementations without changing the rest of the code.

Step 4: MCP Integration

Model Context Protocol (MCP) lets AI agents access Git, Firebase, and other tools directly. I configure this so agents can work with the codebase intelligently.
What I do:
  1. Create .cursor/mcp.json with MCP server configurations for Git and Firebase
  2. Configure permissions for Git commits and Firebase schema access
Why this works: When AI agents can access Git and Firebase directly, they can make intelligent decisions. They can read the database schema. They can commit changes.
They can understand the full context of the project.

Verification Checklist

Before I consider The Big Rig deployed, I verify everything:
  • [ ] Next.js is running on Port 3000
  • [ ] Next.js successfully connects to cloud services
  • [ ] Firebase credentials are configured
  • [ ] Turborepo build pipeline works (pnpm turbo build)
  • [ ] MCP integration is functional
If any item fails, I fix it. No exceptions. The foundation must be solid before I build on top of it.
Why Verification Matters //
The Big Rig is not just a framework - it's a complete architecture. Every component must work before I start building features. Verification prevents hours of debugging later. When working with AI agents, broken foundations lead to cascading failures.

Why This Architecture Works for AI Agent Orchestration

I built The Big Rig this way because it solves specific problems I face when building with an AI colony. Here's why each piece matters:

Rigid Core, Flexible Edge

The Engine (Turborepo, Next.js, Firebase, MCP, directory layout) stays fixed-that's System Stability. The packages (ui, content-engine, newsletter, agent-chat-history, future tools) are Functional Extensibility. Rigidity enables flexibility. Without a stable core, the Edge has nothing to plug into.

Predictable Structure

AI agents can navigate the codebase because the structure is always the same. They know where to find components, where to add features, and where to look for configuration.

Clear Separation

Frontend and backend logic are unified within the monorepo. AI agents can work on modules without breaking the core system. The Turborepo configuration handles builds automatically.

Integrated Vector System

AI agents need memory. The vector database interface provides a unified way to store and retrieve context. They can learn and remember decisions across the entire project.

MCP Integration

Agents can access Git, Firebase, and other tools directly. They can read schemas, commit changes, and understand the full project context.

Turborepo Orchestration

Build processes are coordinated automatically. Agents don't have to figure out build order or dependencies. They just run pnpm turbo build and everything works.

Extractable Services (The Flexible Edge)

The rigid core enables a flexible edge. I can add, swap, or extract packages (ui, content-engine, newsletter, agent-chat-history, future tools) without touching the Engine. The packages/ directory is the plug-in layer-add what you need, extract what you sell.

This isn't theoretical. This is how I actually work. This is the structure that lets me build faster, with fewer errors, and with AI agents that actually understand what they're doing.

Common Pitfalls I've Learned to Avoid

These are the mistakes that cost me hours. Learn from them. Don't repeat them.
1

Don't Skip Verification

If port 3000 is already in use, fix it before proceeding. Broken ports break everything.

The Fix: Always check port availability first. Kill conflicting processes or change ports before starting services.

2

Don't Modify the Core Directory Structure

The rigid core (apps/, packages/, turbo.json, Firebase schema) depends on this exact layout. AI agents expect it. I expect it. The flexible packages can evolve-the Engine cannot.

The Fix: Keep the core structure fixed. Add new packages to packages/ as needed. Document any changes clearly and update all related configurations.

3

Don't Skip the Vector Database Setup

AI memory requires Firebase vector storage to be correctly configured. Without it, agents can't remember context or learn from previous work.

The Fix: Set up your Firebase project and vector indexes during initial deployment. Test the connection to ensure AI memory is functional.

4

Don't Assume Agents Understand Implicit Patterns

Make everything explicit. Document the structure. Show the commands. Leave nothing to interpretation.

The Fix: Write explicit documentation. Include examples. Show exact commands. Assume agents need every detail spelled out.

Conclusion: When Everything Works

When all verification checks pass, when Next.js is serving on 3000, when Turborepo is orchestrating builds, and when the Firebase vector database is ready - that's when The Big Rig is alive.
The rigid core is poured. The Engine is locked. The plug-in layer is ready.
Now I can build. I add packages (content-engine, newsletter, agent-chat-history, future tools) without touching the foundation. AI agents can work. The colony can operate.
Everything has a place, and every place has a purpose. The core stays stable so the edge can flex.
This is my standard. This is The Big Rig. This is how I set up every local development project because it works, it's predictable, and it's designed for AI agent orchestration from the ground up.

Download the Big Rig Brief for your AI Agents

The Big Rig Brief
The Big Rig Brief for AI Agents
Want the complete brief for AI agents? Download the Master Project Brief - the exact protocol I use when initializing The Big Rig with AI agents.
Download the Big Rig BriefMaster Project Brief (MD)

This markdown file contains the complete linear execution plan for AI agents to deploy The Big Rig from ground zero. Share it with your AI agents, save it for reference, or use it as the foundation for your own projects.