Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Subito project is organized as a monorepo managed by pnpm workspaces and orchestrated by Turborepo. This architecture allows for the co-location of multiple applications (apps) and reusable libraries (packages) within a single repository, facilitating shared configurations, type safety across the stack, and efficient build caching.
The repository follows a standard division between apps/, which contains deployable services like the API and Dashboard, and packages/, which houses shared logic, UI components, database schemas, and configurations.
Sources: package.json:28, turbo.json:1-5
Workspace Architecture
The project utilizes a modular architecture where specific functionalities are isolated into internal packages. These packages are then consumed by the applications using the workspace:* protocol, ensuring that local changes in a package are immediately reflected in the dependent apps without requiring external publishing.
The following diagram illustrates the high-level dependency flow between the primary applications and the internal library packages.
The diagram shows how both applications and packages depend on centralized configuration packages, while specific logic like the database or UI is shared where relevant.
Sources: apps/api/package.json:28-44, apps/dashboard/package.json:15-26, packages/ui/package.json:34-37
Core Applications
The monorepo contains two primary applications located in the apps/ directory:
1. API Service (apps/api)
A backend service built with Hono and running on Node.js. It serves as the central business logic layer.
- Key Dependencies:
hono,bullmq,firebase-admin,ioredis. - Workspace Links: Depends on
@subito/dbfor data persistence and@subito/sharedfor common logic. - Runtime: Executed using
tsxin development and compiled viatsup.
Sources: apps/api/package.json:1-44
2. Dashboard (apps/dashboard)
A frontend application built with Next.js.
- Key Dependencies:
next,react,lucide-react. - Workspace Links: Depends on
@subito/uifor shared components and styling. - Runtime: Uses Next.js Turbopack for optimized development.
Sources: apps/dashboard/package.json:1-26
Shared Packages
Internal libraries located in the packages/ directory provide a single source of truth for the entire monorepo.
| Package | Purpose | Key Technologies |
|---|---|---|
@subito/db | Database schema, migrations, and seeding. | Drizzle ORM, PostgreSQL, drizzle-kit |
@subito/ui | Shared UI component library. | React 19, Tailwind CSS, Shadcn/UI |
@subito/shared | Cross-stack constants, types, and utils. | TypeScript |
@subito/utils | Specialized helper functions (e.g., JWT). | Zod |
@subito/eslint-config | Unified linting rules (Base, Next.js, React). | ESLint 9 |
@subito/typescript-config | Shared TS compiler configurations. | TypeScript 5.9.3 |
Sources: packages/db/package.json:1-35, packages/ui/package.json:1-55, packages/shared/package.json:1-20, packages/eslint-config/package.json:1-20
Build and Task Orchestration
Turborepo is configured via turbo.json to manage the execution of scripts across the workspace. It defines a task pipeline that respects dependencies between packages.
Task Pipeline
The pipeline ensures that if Package A depends on Package B, Package B is built before Package A.
| Task | Dependency | Cacheable |
|---|---|---|
build | ^build (dependencies build first) | Yes |
lint | ^lint | Yes |
typecheck | ^typecheck | Yes |
dev | None | No (Persistent) |
Sources: turbo.json:22-55
Global Environment Variables
Turborepo tracks specific environment variables to determine if a cache should be invalidated. Key variables include:
DATABASE_URLfor database operations.REDIS_URLfor queueing and caching.JWT_SECRETfor authentication logic.
Sources: turbo.json:4-20
Development Workflow
The monorepo is configured for a unified development experience using the root package.json to trigger tasks across all workspaces.
{
"scripts": {
"build": "turbo build",
"dev": "turbo dev",
"lint": "turbo lint",
"format": "turbo format",
"typecheck": "turbo typecheck"
}
}
Sources: package.json:4-12
Database Management
The @subito/db package provides scripts for managing the PostgreSQL lifecycle:
db:generate: Creates SQL migrations via Drizzle Kit.db:migrate: Applies migrations to the database.db:seed: Populates the database usingsrc/seed.ts.
Sources: packages/db/package.json:12-16
Conclusion
The Subito monorepo structure provides a robust foundation for a full-stack application. By leveraging Turborepo and pnpm workspaces, it minimizes configuration drift and ensures that shared logic—from UI components in @subito/ui to the Drizzle schema in @subito/db—is consistently applied across both the API and Dashboard applications.