Skip to main content

Monorepo Structure

Both Pulse and Control Center use Turborepo with npm workspaces. The shared package is built first since both api and web depend on it.

Pulse Directory Layout​

Pulse/
├── apps/
│   ├── api/                          # Express backend (Port 3000)
│   │   ├── src/
│   │   │   ├── routes/               # 39 route modules (/api/v1/*)
│   │   │   ├── services/             # 57 service files
│   │   │   ├── queues/               # 27 BullMQ queues + workers
│   │   │   ├── middleware/            # Auth, validation, RBAC, rate limiting
│   │   │   │   ├── auth.ts           # JWT verification (Passport.js)
│   │   │   │   ├── requireWorkspace.ts  # Workspace context + RBAC
│   │   │   │   ├── requireFeature.ts    # Feature flag gating
│   │   │   │   ├── requireQuota.ts      # Usage quota enforcement
│   │   │   │   ├── requireSuperAdmin.ts # Super admin guard
│   │   │   │   ├── validate.ts          # Zod schema validation
│   │   │   │   ├── rateLimiter.ts       # aiLimiter, authLimiter
│   │   │   │   ├── errorHandler.ts      # Global error handler
│   │   │   │   ├── upload.ts            # File upload (multer)
│   │   │   │   └── responseTimeTracker.ts # Response time logging
│   │   │   ├── utils/                # Helpers and utilities
│   │   │   └── index.ts              # App entry point
│   │   ├── prisma/
│   │   │   └── schema.prisma         # 69+ models, ~1940 lines
│   │   └── package.json
│   │
│   └── web/                          # React frontend (Port 5173)
│       ├── src/
│       │   ├── pages/                # 58+ page components
│       │   │   ├── accounts/         # Social account management
│       │   │   ├── admin/            # Super admin dashboard
│       │   │   ├── ads/              # Ad campaigns & auto-boost
│       │   │   ├── ai-brain/         # AI brain / chat
│       │   │   ├── ai-tools/         # AI generation tools
│       │   │   ├── analytics/        # Performance analytics
│       │   │   ├── approvals/        # Approval workflows
│       │   │   ├── audience/         # Audience CRM & segments
│       │   │   ├── auth/             # Login, register, OAuth
│       │   │   ├── checkout/         # Payment flow
│       │   │   ├── client/           # Client portal
│       │   │   ├── commerce/         # Revenue & orders
│       │   │   ├── competitors/      # Competitor tracking
│       │   │   ├── composer/         # Multi-platform composer
│       │   │   ├── conversation-engine/  # ICE configuration
│       │   │   ├── conversations/    # Unified inbox
│       │   │   ├── dashboard/        # Main overview
│       │   │   ├── drafts/           # Draft posts
│       │   │   ├── ecommerce/        # Store management
│       │   │   ├── intelligence/     # Gap analysis & insights
│       │   │   ├── landing/          # Public landing page
│       │   │   ├── posts/            # Published posts
│       │   │   ├── predictions/      # AI predictions
│       │   │   ├── pricing/          # Plan comparison
│       │   │   ├── reports/          # Client reports
│       │   │   └── scheduler/        # Schedule management
│       │   ├── components/           # Shared UI components (shadcn/ui)
│       │   ├── stores/               # Zustand stores
│       │   ├── hooks/                # Custom React hooks
│       │   ├── lib/                  # API client, utils, cn()
│       │   └── i18n/                 # EN + AR translations
│       │       ├── en/               # English JSON files
│       │       └── ar/               # Arabic JSON files (RTL)
│       └── package.json
│
├── packages/
│   └── shared/                       # Shared types & validators
│       ├── src/
│       │   ├── types/                # 29 type definition files
│       │   └── validators/           # 29 Zod schema files
│       └── package.json
│
├── docker-compose.yml                # Dev: PostgreSQL 16 + Redis 7
├── docker-compose.prod.yml           # Prod: full stack deployment
├── turbo.json                        # Turborepo pipeline config
└── package.json                      # Root workspace config

Control Center Directory Layout​

UniPulse-Control-Center/
├── apps/
│   ├── server/                       # Express backend
│   │   ├── src/
│   │   │   ├── services/
│   │   │   │   ├── docker.service.ts     # Container lifecycle
│   │   │   │   ├── vps.service.ts        # System metrics (systeminformation)
│   │   │   │   ├── metrics.service.ts    # 3s collection, 60s storage, 30d retention
│   │   │   │   ├── github.service.ts     # PRs, workflow runs, CI stats
│   │   │   │   ├── auth.service.ts       # JWT 15m access + 7d refresh
│   │   │   │   ├── tasks.service.ts      # Kanban: TODO/IN_PROGRESS/IN_REVIEW/DONE
│   │   │   │   ├── notifications.service.ts
│   │   │   │   └── audit.service.ts
│   │   │   ├── routes/
│   │   │   ├── socket/                   # Socket.IO namespaces
│   │   │   │   ├── metrics.ts            # /metrics namespace
│   │   │   │   ├── docker.ts             # /docker namespace
│   │   │   │   └── notifications.ts      # /notifications namespace
│   │   │   └── index.ts
│   │   └── prisma/                       # SQLite schema (7 models)
│   │
│   └── web/                              # React frontend
│       └── src/
│           └── pages/
│               ├── Home.tsx
│               ├── VPSMonitor.tsx
│               ├── DockerManager.tsx
│               ├── SocialStats.tsx
│               ├── TaskTracker.tsx
│               ├── PRTracking.tsx
│               ├── CIAnalysis.tsx
│               ├── Deployments.tsx
│               ├── Notifications.tsx
│               ├── Settings.tsx
│               └── Login.tsx
│
├── ecosystem.config.js               # PM2: max_memory_restart 500M, max_restarts 10, JSON logging
├── nginx/                            # SSL, rate limiting (5/s auth, 30/s API), WebSocket proxy
├── setup.sh                          # Server setup script
└── deploy.sh                         # Deployment script

Package Dependency Graph​

Running the Monorepo​

Development Commands​

# Install all dependencies (from root)
npm install

# Start all dev servers (API + Web + shared watch)
npm run dev

# Start only the API
npm run dev --filter=api

# Start only the web app
npm run dev --filter=web

# Build all packages (respects dependency order)
npm run build

# Build only shared package
npm run build --filter=shared

# Type check everything
npm run typecheck

Turborepo Pipeline​

The turbo.json configuration ensures correct build ordering and enables caching:

TaskDependenciesCacheable
build^build (builds dependencies first)Yes
dev^buildNo
typecheck^buildYes
lint-Yes

The shared package always builds first since both api and web import from @unipulse/shared.

Turborepo Cache

Turborepo caches build outputs. If you change only apps/web, running npm run build will skip rebuilding packages/shared and apps/api if they haven't changed. This significantly speeds up CI builds.

Cross-Reference