💠 Omni-tRPC-Stack

The Ultimate Fullstack Monorepo Engine

Next.js 16 • Nest.js • Expo • tRPC • Prisma

Explore Documentation • Report Bug

---

🌟 Overview

Omni-tRPC-Stack is a high-performance, production-ready Monorepo architecture. It eliminates the friction between your Backend and multiple Frontends by providing a unified, 100% Type-Safe communication layer.

Why Omni-Stack?

• 🧩 Single Source of Truth: Forget about duplicating validation logic. Use shared Zod schemas to validate data across Web, Mobile, and Server simultaneously. Change once, update everywhere.
• 🛡️ E2E Type-Safety (Zero-runtime errors): Experience the magic of tRPC. Catch API breaking changes at compile time before they ever reach production. If your backend changes, your frontend won't build until it's fixed.
• 📱 Native Mobile Integration: Not just a web-wrapper. A fully-fledged Expo (React Native) application is baked into the monorepo, sharing logic and state with your web apps out of the box — including deep linking on both iOS and Android.
• 🚢 DevOps-as-a-Service: Industrial-grade deployment. From Docker Orchestration to automated GitHub Actions CI/CD for your own VPS. It's not just a boilerplate; it's a complete production pipeline.
• 🔐 Advanced Security Included: Full 2FA (TOTP) with backup codes, account lockout protection, role-based access control (RBAC), and secure session management are pre-configured across web and mobile.

---

🛠 Tech Stack

🏗 Infrastructure & Monorepo

• Monorepo: PNPM Workspaces + Turborepo
• API Layer: tRPC (End-to-End Type-Safety)
• Database: PostgreSQL + Prisma ORM
• DevOps: Docker, Nginx Proxy Manager, GitHub Actions

💻 Frontend & Mobile

• Web Framework: Next.js 16 (App Router)
• Mobile: Expo (React Native) + Expo Router
• UI Toolkit: HeroUI (ex. NextUI) + TailwindCSS
• State: Zustand + TanStack Query
• i18n: react-i18next (Mobile) + next-intl (Web) with shared locale support

⚙️ Backend

• Core: Nest.js (Modular Architecture)
• Auth: NextAuth.js (Web) + JWT (Mobile)
• OAuth Providers: Google, Facebook, Apple
• Validation: Shared Zod schemas across the entire Monorepo
• AI: Ollama (self-hosted LLM) via Vercel AI SDK — streaming assistants for admin & website

📁 Project Structure

.
├── apps
│ ├── admin # Admin Dashboard (Next.js)
│ ├── website # Customer Web App (Next.js)
│ ├── mobile # Cross-platform App (Expo / React Native)
│ ├── server # Backend API (Nest.js)
├── packages
│ ├── api # Shared tRPC router & client logic & shared Zod validation schemas
│ ├── store # Shared state management (Zustand)
│ ├── prisma # Database schema & Prisma Client (Shared ORM)
│ ├── ui # Shared theme provider
│ ├── next-auth # Centralized Auth configurations & providers
│ ├── shared # Common components, hooks, utilities and constants
│ ├── ai # AI assistants & tools (Ollama, Vercel AI SDK)
│ ├── i18n # Shared translations (en/uk)
│ ├── tailwind-config # Base TailwindCSS configurations
│ └── eslint-config # Centralized linting rules
├── docker-compose.local.yml # Local development orchestration
└── docker-compose.prod-ci.yml # Production deploy orchestration

🔐 Authentication & Security

The stack ships with a complete, production-grade auth system that works across web and mobile.

Features

Feature	Web (Next.js)	Mobile (Expo)
Email + Password sign-in	✅	✅
OAuth (Google, Facebook, Apple)	✅	✅
Two-Factor Authentication (TOTP)	✅	✅
2FA backup codes	✅	—
Account lockout (brute-force protection)	✅	✅
Role-based access control (RBAC)	✅	✅
Admin-only domain guard	✅	—
JWT session tokens	—	✅
NextAuth.js sessions	✅	—

2FA Flow

Web: Users can enable 2FA during sign-up or from their profile. After sign-in, if 2FA is active they are redirected to /auth/two-factor/verify. If they lose their authenticator they can use a one-time backup code. The setup flow lives at /auth/two-factor/setup.

Mobile: After a successful credential login, if the account requires 2FA, the user is pushed to the verify-2fa screen with a short-lived mfaToken. On success, the full JWT session is stored in the native auth store.

Account Lockout

After repeated failed login attempts the account is automatically locked until lockedUntil expires. The schema tracks failedLoginAttempts, lockedUntil, passwordChangedAt, isOnline, and lastActiveAt.

🤖 AI Assistants

The @package/ai package provides two built-in AI assistants powered by a self-hosted Ollama model. Both stream responses over tRPC WebSocket subscriptions (useSubscription) so the UI updates in real time.

Public assistant (Website)

Embedded as a floating chat widget (AiAssistantPlugin) on the website landing page. It answers questions about the project architecture and guides visitors through the stack. Quick-action buttons let users ask about the tech stack, project structure, mobile integration, or DevOps with one click.

Capabilities

Tool	Description
getWelcomeMessage	Returns assistant greeting and capability overview
getSystemStatus	Reports platform health and DB status
getProjectInfo	Deep-dives into stack, features, mobile, security, devops, or structure
getPackageDetails	Lists all monorepo packages and their purpose

The public assistant cannot call any admin tools. Requests for ban/unban, user deletion, or statistics return a hard-coded permission error.

Admin assistant (Admin Dashboard)

Embedded in the protected admin layout so it is available on every admin page. It uses the same streaming widget but exposes a full set of admin tools with a confirmation step for destructive actions (ban, unban, delete, unlock).

Available tools

Category	Tools
Users	getUserList, getAdminList, getRecentUsers, findUser, banUser, unbanUser, deleteUser, exportUsersToCSV
Stats	getUserCounts, getActiveUsers, getGrowthRate, getRoleDistribution, getRegistrationsByDay, getTopUsers
Security	getUserSessions, unlockUser, getSecurityAlerts
Invites	getInviteList, createInvite, revokeInvite
System	getWelcomeMessage, getSystemStatus, getProjectInfo

Destructive tools (banUser, unbanUser, deleteUser, unlockUser) trigger a confirmation dialog before execution. The assistant never invents data — it always calls a tool if one exists.

Configuration

Set these environment variables on the server:

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_BASE_MODEL=llama3

The model name can be any model available in your Ollama instance. Swap it out without changing application code.

Architecture

packages/ai/
├── assistants/
│   ├── admin.assistant.ts   # Admin streaming handler (tool filtering by prompt)
│   └── public.assistant.ts  # Public streaming handler (read-only tools)
├── agent/
│   └── index.ts             # Multi-step agent loop (up to 6 steps, confirmation support)
├── tools/
│   ├── users.tools.ts       # User CRUD + CSV export
│   ├── stats.tools.ts       # Analytics and growth metrics
│   ├── security.tools.ts    # Sessions, lockout, security alerts
│   ├── invites.tools.ts     # Invite management
│   └── system.tools.ts      # System health + project knowledge base
└── index.ts                 # handleAssistant() — routes to admin or public handler

🧠 Claude Code Agent Workflow

This project includes a built-in AI agent workflow powered by Claude Code and Todoist. Tasks are created and tracked in Todoist, Claude implements the code, GitHub Copilot generates commit messages, and a git hook closes the task and opens a PR automatically after push.

How it works

/create-task "add user avatar upload"
  ↓ Claude analyzes the codebase and creates a structured task in Todoist
/work-on-tasks
  ↓ Claude fetches the task, reads title + description, does a dry run
  ↓ Creates a branch: feature/todoist-{id}-{slug}
  ↓ Implements: schema → service → router → frontend
  ↓ Reports changed files
Copilot generates commit message in VS Code → user commits → git push
  ↓ post-push hook runs automatically:
     ✅ Closes task in Todoist
     🔗 Creates GitHub PR with task description as body
     💬 Adds PR link as comment to the Todoist task

Setup

1. Get your Todoist API token from todoist.com/app/settings/integrations/developer

2. Add to your shell profile (~/.zshrc or ~/.bashrc):

   export TODOIST_API_TOKEN=your_token_here
   

3. Configure git hooks (one-time):

   git config core.hooksPath .githooks
   chmod +x .githooks/post-push
   

4. Install GitHub CLI and authenticate:

   brew install gh && gh auth login
   

Commands

Command	Description
/create-task "idea"	Analyzes codebase, composes a structured task and creates it in Todoist
/work-on-tasks	Fetches today's P1 @claude tasks and implements the top one
`/work-on-tasks {taskId}