Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
The Timesheet Zone (tsz) project is a modern monorepo application consisting of a .NET backend and a TanStack Start frontend. It is designed as a Single Page Application (SPA) template for managing business entities such as customers, users, contracts, and leave types.
This guide provides the necessary technical instructions to set up the development environment, execute the primary application components, and understand the project's architectural standards.
Sources: CLAUDE.md:1-3, package.json:1-5
Environment Setup
The project uses bun as the primary package manager and execution runtime for the frontend and workspace-level tasks. The backend relies on the .NET SDK for building and running the API services.
Prerequisites
- Bun: Required for managing frontend dependencies and running workspace scripts.
- .NET SDK: Required for the backend API and integration tests.
- SQLite: Used as the default database engine for development.
Sources: CLAUDE.md:5, REVIEW.md:15-18
Development Commands
The root package.json provides orchestrated scripts to start both the frontend and backend simultaneously or individually.
| Command | Action |
|---|---|
bun run dev | Starts the TanStack Start web application. |
bun run dev:api | Starts the .NET API using dotnet watch. |
bun run test:all | Executes both frontend Vitest tests and backend .NET tests. |
bun run check | Runs linting and health checks across the workspace. |
Sources: package.json:10-18, packages/web/README.md:10-13
Architecture and Data Flow
The system follows a decoupled architecture where the frontend communicates with the .NET backend via an OpenAPI-compliant REST API.
The diagram above illustrates the request flow from the user interface through the generated API client to the modularized backend services.
Sources: packages/web/README.md:21-31, REVIEW.md:4-10
Backend Structure
The backend is modularized to prevent tight coupling. Configuration responsibility is moved to specific module extension methods (e.g., AddCustomerModule) rather than cluttering the main Program.cs. Connection strings are managed via appsettings.json.
Sources: REVIEW.md:4-48
Frontend Structure
The web package uses TanStack Start with file-based routing. The src/api directory contains a generated TypeScript schema based on the backend's OpenAPI specification.
The directory structure enforces separation between routing, API definitions, and reusable UI components.
Sources: packages/web/README.md:21-31, packages/web/package.json:8-10
Development Standards
Naming Conventions
Descriptive naming is mandatory across the project. Acronyms, single-letter variables, and abbreviated names (e.g., err, e, ct) are forbidden in favor of full words like error, submitEvent, and cancellationToken.
Sources: CLAUDE.md:8-10
Form Handling and Validation
Forms are implemented using @tanstack/react-form and must be validated using Zod schemas. Ad-hoc validation functions are discouraged. UI components should utilize the FieldError component to ensure consistent error rendering.
Sources: packages/web/CLAUDE.md:9-15, REVIEW.md:65-90
Server Functions
All createServerFn instances must include an .inputValidator using a Zod schema. These schemas should be shared between the client forms and the server functions to ensure data integrity across the network boundary.
Sources: packages/web/CLAUDE.md:17-21
API Integration
The frontend client is synchronized with the backend using an OpenAPI generator.
This process ensures that the TypeScript types used in the frontend always match the latest backend contracts.
Sources: packages/web/package.json:21, packages/web/CLAUDE.md:28-29
Conclusion
By following this "Getting Started" guide, developers can establish a consistent environment using bun and .NET. Adherence to the project's strict naming conventions, Zod-based validation, and modular backend configuration is essential for maintaining the scalability and health of the tsz repository.