Welcome to Tsz Documentation
Relevant source files
The following files were used as context for generating this wiki page:
Tsz (Timesheet Zone) is a modern monorepo application designed for time tracking and administrative management. The project utilizes a .NET backend and a TanStack Start frontend, providing a high-performance, type-safe environment for managing users, contracts, customers, and leave allowances.
The documentation covers the system's architecture, frontend development standards, and administrative modules. The project emphasizes strict naming conventions, descriptive variable names, and a robust separation of concerns between modules.
Sources: CLAUDE.md:1-12, packages/web/README.md:1-5
System Architecture
Tsz follows a monorepo structure with a clear boundary between the frontend web package and the .NET API. The architecture is designed to support modularity, though recent refactorings have focused on moving from a monolithic configuration to per-module extensions to reduce coupling.
Project Structure Overview
The diagram shows the high-level organization of the Tsz monorepo.
Sources: packages/web/README.md:14-25, REVIEW.md:25-45, CLAUDE.md:1-5
Core Technologies
| Layer | Technology | Description |
|---|---|---|
| Frontend | TanStack Start | Full-stack React framework utilizing TanStack Router and Query. |
| Backend | .NET | Robust API layer with Entity Framework Core and SQLite support. |
| Database | SQLite | Local database support via animals.db and tsz.db. |
| Validation | Zod | Used for schema-based validation on both client and server functions. |
| Styling | Tailwind CSS v4 | Utility-first CSS framework for UI styling. |
| UI Kit | shadcn/ui | Component library used for standardized UI elements. |
Sources: packages/web/README.md:3-5, packages/web/CLAUDE.md:3-12, REVIEW.md:7-15
Frontend Development Standards
The frontend is built on TanStack Start and adheres to strict development guidelines to ensure maintainability and type safety.
Route Management
Tsz uses file-based routing. Files or directories prefixed with - are excluded from routing and are used to colocate private components, schemas, and server functions.
Sources: packages/web/CLAUDE.md:21-25
Form Handling and Validation
Forms are managed using @tanstack/react-form with the following requirements:
- Validation: Every form must be validated via a Zod schema using the form's validator adapter. Inline ad-hoc validators are prohibited.
- Error Rendering: Field errors must be rendered using the shared
<FieldError />component to prevent logic drift. - Server Functions:
createServerFnmust use.inputValidatorwith a Zod schema as the source of truth for input types.
Sources: packages/web/CLAUDE.md:7-19
API Integration
The API client is an OpenAPI-fetch implementation with types generated from the .NET backend.
- Type Generation:
bun run gen:apigeneratessrc/api/schema.tsfrom the local .NET server. - Data Fetching: Routes use loaders to pre-fetch data via server functions located in
features/.
Sources: packages/web/package.json:20, packages/web/CLAUDE.md:27-28
Administrative System
The administrative interface provides oversight of the system's core entities. Access is restricted to users with the Admin role.
Admin Dashboard
The dashboard provides a high-level overview of system statistics, fetching counts for customers, users, contracts, and leave types.
Sources: packages/web/src/routes/_authed/admin/index.tsx:29-43
The sequence shows the data flow for loading the administrative dashboard.
Sources: packages/web/src/routes/_authed/admin/index.tsx:6-10, packages/web/src/api/schema.ts:316-339
Navigation and UI
The system uses a top navigation bar (Euricom navbar) that dynamically adjusts based on the user's role and screen size.
| Navigation Item | Path | Icon | Role Requirement |
|---|---|---|---|
| Time Entry | /time-entry | Clock | All |
| Timesheets | /timesheets | CalendarDays | All |
| Customers | /admin/customers | Building2 | Admin |
| Users | /admin/users | Users | Admin |
| Contracts | /admin/contracts | FileText | Admin |
| Leave Types | /admin/leave-types | CalendarClock | Admin |
Sources: packages/web/src/components/app-navbar.tsx:26-40, packages/web/src/components/app-navbar.tsx:114-118
Data Models
The system architecture relies on several key entities defined in the OpenAPI schema.
User and Leave Management
Users are assigned roles (Admin, User, ClientManager) and have associated leave allowances. Allowance modes can be Unlimited or Limited.
Sources: packages/web/src/api/schema.ts:646-648, packages/web/src/api/schema.ts:747-750
Contract System
Contracts link customers and consultants (users) and contain multiple tasks with specific day rates.
Sources: packages/web/src/api/schema.ts:517-531
This ER diagram illustrates the relationships between core entities in the Tsz system.
Sources: packages/web/src/api/schema.ts:517-640, packages/web/src/api/schema.ts:720-745
Summary
Tsz Documentation outlines a structured approach to building a timesheet and administrative management tool. By utilizing a shared schema between the .NET backend and TanStack-powered frontend, the project ensures high technical accuracy and type safety. The modular architecture and strict frontend guidelines facilitate scalable development and clear separation of business logic from UI implementation.
Sources: REVIEW.md:47-60, packages/web/CLAUDE.md:1-5