Full Stack Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Timesheet Zone (TSZ) project is a monorepo application featuring a .NET backend and a React-based frontend built with TanStack Start. The architecture emphasizes type safety across the stack by utilizing OpenAPI for API contract definition and Zod for runtime validation on the frontend.
The project structure separates concerns between a modular .NET API and a file-based routing frontend. High-level communication is handled via RESTful endpoints, with the frontend leveraging openapi-fetch and TanStack Query for data synchronization and state management.
Sources: CLAUDE.md:1-5, packages/web/README.md:1-10
Backend Architecture
The backend is a .NET application designed with a modular approach. While earlier iterations featured a monolithic Program.cs, recent refactors have moved towards module-specific configuration extensions (e.g., AddCustomerModule) to improve separation of concerns.
Data Persistence and Services
The system utilizes SQLite as the primary database, with AppDbContext serving as the main entry point for data operations. Business logic is encapsulated within service classes (e.g., UserService, CustomerService), which handle database interactions, transaction management, and error handling.
Sources: REVIEW.md:4-40, CHANGELOG.md:4-10
API Structure
The API follows REST principles, exposing resources through specific path-based endpoints. It includes a global OpenAPI specification used to generate TypeScript types for the frontend.
| Feature | Description |
|---|---|
| Authentication | S6 OAuth implemented with Entra ID. |
| OpenAPI | Integrated via AddOpenApi with schema transformers for nullability/requirement strictness. |
| Serialization | Strict JSON number handling configured in HttpJsonOptions. |
Sources: REVIEW.md:103-125, CHANGELOG.md:5-7
Frontend Architecture
The frontend is built using TanStack Start, utilizing file-based routing and server functions for data fetching and mutations.
Component and UI Layer
The UI is constructed using shadcn/ui components and Tailwind CSS v4. The layout is managed through a root route and authenticated layouts that include a top navigation bar (Euricom navbar).
This diagram illustrates the frontend component hierarchy and layout nesting.
Sources: packages/web/src/routes/__root.tsx:5-30, packages/web/src/routes/_authed.tsx:35-45, CHANGELOG.md:14-16
Data Flow and Validation
Frontend data flow relies on TanStack Router loaders and Server Functions (createServerFn). Validation is enforced using Zod schemas, which are shared between the UI forms and server functions to ensure consistency.
The sequence of a typical data mutation request from the browser to the backend.
Sources: packages/web/CLAUDE.md:12-25, packages/web/src/features/users/users.functions.ts:9-40
Data Models and Contracts
The system shares a contract defined by the OpenAPI schema. Key entities include Customers, Users, Contracts, and Leave Types.
Core Entities
| Entity | Primary Fields | Relationships |
|---|---|---|
| User | ID, Name, Email, Role | Has Leave Allowances |
| Customer | ID, Number, Name, Contact | Linked to Contracts |
| Contract | ID, Number, Subject, StartDate | Links Customer and Consultant (User) |
| Leave Type | ID, Name, DefaultDays | Used in User Leave Allowances |
Sources: packages/web/src/api/schema.ts:650-750
Entity Relationships
Logical relationship between core system entities derived from the API schema.
Full Stack Integration
The bridge between the .NET API and TanStack Start frontend is managed through generated types. The command bun run gen:api reads the OpenAPI JSON from the running .NET server to update src/api/schema.ts.
Authentication Flow
Authentication is handled at the route level using a beforeLoad guard in the _authed.tsx route. This guard checks for a valid session and fetches the current user from /api/users/me before allowing access to protected pages.
Sources: packages/web/package.json:20, packages/web/src/routes/_authed.tsx:20-35
Conclusion
The TSZ architecture provides a robust full-stack environment by combining the type-safe capabilities of .NET on the backend with the modern, file-routed structure of TanStack Start on the frontend. The use of shared schemas and automated type generation ensures that data integrity is maintained from the database to the browser.