Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:The Thoth project operates as a TypeScript monorepo managed by pnpm and Turbo. It organizes the codebase into distinct workspaces for runnable services, shared libraries, infrastructure definitions, and technical documentation. This structure facilitates code sharing across the stack while maintaining clear boundaries between the frontend, backend, and core logic.
Sources: package.json:1-10, README.md:1-10, apps/web/next.config.ts:8-12
Layout and Organization
The repository follows a standardized directory layout to separate concerns. Services reside in the apps/ directory, while reusable logic and components stay in the packages/ directory.
Directory Overview
| Directory | Purpose | Contents |
|---|---|---|
apps/ | Runnable services | Web frontend (Next.js) and API (Express/MCP). |
packages/ | Shared libraries | Core logic, utility functions, and UI components. |
infra/ | Infrastructure | Terraform configurations. |
docs/ | Documentation | Decision logs and module specifications (SDD). |
.claude/ | AI Tools | Claude Code skills and custom instructions. |
Sources: README.md:5-10, CLAUDE.md:16-20
The following diagram visualizes the primary filesystem hierarchy:
The diagram shows the logical grouping of services, libraries, and documentation within the root directory.
Sources: README.md:5-10, CLAUDE.md:16-20
Package Relationships
Workspaces within the monorepo reference each other using pnpm workspace protocols. The shared packages provide a foundation for the application-level services.
- @thoth/web: Depends on
@thoth/uiand@thoth/utils. - @thoth/api: Depends on
@thoth/coreand@thoth/utils. - @thoth/core: Provides core domain logic and dependency injection (Inversify).
- @thoth/ui: Provides shared React components and Tailwind CSS styles.
- @thoth/utils: Contains shared utilities like logging (Pino), validation (Zod), and error codes.
Sources: apps/web/package.json:17-27, apps/api/package.json:20-23, packages/core/package.json:23-24, packages/utils/package.json:20-25, packages/ui/package.json:15-22
Dependency Flow
This diagram illustrates how application workspaces consume shared packages.
Sources: apps/web/package.json:18-19, apps/api/package.json:20-21
Tooling and Workspace Scripts
The monorepo uses a unified set of tools for linting, testing, and building across all packages. Execution is orchestrated via the root package.json using pnpm recursive commands and Turbo.
Core Tools
- Package Manager:
pnpm@12.15.0 - Build Orchestration:
turbo@2.11.10 - Linting/Formatting:
biome - Testing:
vitest - Bundling:
tsup(for packages) andnext(for web).
Sources: package.json:6-66, packages/core/package.json:16-16, apps/web/package.json:7-12
Root Scripts
| Command | Action |
|---|---|
pnpm dev | Runs all workspaces in development mode in parallel. |
pnpm build | Uses Turbo to run the build pipeline across the monorepo. |
pnpm verify | Executes a comprehensive check including secrets, linting, typechecking, and tests. |
pnpm lint | Runs Biome checks for code style and quality. |
pnpm test | Executes Vitest runs across all workspaces. |
pnpm arch | Runs dependency-cruiser to validate architectural boundaries. |
Sources: package.json:11-30
Development Workflow
Technical documentation and architectural rules are stored alongside the code to ensure they remain current.
- Architecture Decisions: Stored in
docs/decision-log/to document the "why" behind changes. - Specifications: Module-specific rules (SDD) are located in
apps/*/spec/orpackages/*/spec/. - Self-Correction: The
pnpm spec-checkcommand (usingsdd-spec-check) validates that implementations match their specifications.
Sources: CLAUDE.md:16-20, package.json:21-21
The monorepo structure supports efficient local development and CI/CD by leveraging Turbo's caching and pnpm's workspace management, ensuring that only modified packages and their dependents are rebuilt or retested.
Sources: package.json:54, apps/web/next.config.ts:11-12