Monorepo Workspace Structure
Relevant source files
The following files were used as context for generating this wiki page:
The project is structured as a monorepo containing a .NET backend and a React-based TanStack Start frontend. It utilizes a workspace-based architecture to manage multiple packages and services within a single repository, primarily managed using bun as the package manager and task runner.
Sources: CLAUDE.md:1-3, package.json:5-7
Architecture Overview
The repository follows a Single Page Application (SPA) template pattern, integrating a C# .NET API with a modern TypeScript frontend. The structure promotes separation of concerns by isolating the API logic from the web interface while sharing configuration and development workflows at the root level.
The diagram illustrates the high-level relationship between the root workspace and its primary sub-packages.
Sources: package.json:5-7, CLAUDE.md:1-10, packages/web/README.md:3-5, CHANGELOG.md:8-10
Root Workspace Configuration
The root package.json defines the workspace boundaries and provides centralized scripts for orchestration. It uses the workspaces field to include all directories under packages/*.
Centralized Scripts
| Script | Command | Purpose |
|---|---|---|
dev | bun run --filter 'web-tanstack-start' dev | Starts the frontend development server |
dev:api | dotnet watch run --project packages/api | Starts the .NET API with hot reload |
test:all | bun run test:web && dotnet test tsz.sln | Executes both frontend and backend test suites |
check | bun run --filter '*' check | Runs linting and type checking across all packages |
Sources: package.json:8-19
Package: Web Frontend (packages/web)
The frontend is a "TanStack Start" application. It is located in packages/web and identified in the workspace as web-tanstack-start. It leverages a file-based routing system and an OpenAPI-generated client to interact with the backend.
Internal Directory Structure
src/api/: Contains the auto-generated OpenAPI client and schema definitions.src/features/: Organized by domain (e.g., users, leave-types, contracts), housing business logic and server functions.src/routes/: File-based routing tree using TanStack Router.src/components/: Shared UI components, includingshadcn/uiimplementations.
Sources: packages/web/package.json:2, packages/web/README.md:21-31, packages/web/CLAUDE.md:25-28
Dependency Stack
The web package utilizes the following core technologies:
- Framework: React 19
- Routing: TanStack Router
- Form Management: TanStack React Form with Zod validation
- Styling: Tailwind CSS v4 and shadcn/ui
- API Client: openapi-fetch
Sources: packages/web/package.json:23-41, packages/web/CLAUDE.md:5-15
Package: API Backend (packages/api)
The backend is a .NET application. Recent refactors have moved from a monolithic Program.cs toward a modular configuration approach using extension methods to register services per-module.
Module Configuration Pattern
Configuration is delegated to specific modules (e.g., AnimalModule, CustomerModule) to reduce coupling. Each module manages its own DbContext and service registrations.
The diagram shows the modular service registration pattern recommended in the architectural reviews.
Sources: REVIEW.md:5-45, CHANGELOG.md:8-10
Development Standards
The monorepo enforces specific conventions across all workspaces:
- Package Management:
bunis the mandatory tool for project execution;npmandpnpmare explicitly discouraged. - Naming Conventions: Descriptive naming is required; acronyms and single-letter variables (e.g.,
err,ct) are prohibited. - Documentation:
CLAUDE.mdfiles are maintained at both the root and package levels to provide context-specific development instructions.
Sources: CLAUDE.md:5-12, REVIEW.md:95-97
Summary
The tsz monorepo provides a unified environment for full-stack development. By leveraging Bun workspaces and a modular .NET backend, the structure allows for independent scaling of the frontend and backend components while maintaining strict typing and architectural consistency through OpenAPI and shared Zod schemas.