Coding Conventions
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the architectural patterns, development standards, and stylistic requirements for the project. As a monorepo consisting of a .NET backend and a TanStack Start frontend, these conventions ensure consistency across the stack, facilitate maintainability, and support modular scalability.
Sources: AGENTS.md:1-5, CLAUDE.md:1-5
General Project Standards
The project emphasizes technical clarity and strict environment management. All contributors must follow these foundational rules:
- Package Management: Use
bunexclusively for frontend operations;npmorpnpmare not permitted. - Naming Conventions: Descriptive naming is mandatory. Abbreviations, acronyms, and single-letter variables are prohibited (e.g., use
cancellationTokeninstead ofct,errorinstead oferr). - Concision: Reports and communication should prioritize brevity and technical accuracy over grammatical perfection.
Sources: CLAUDE.md:7-13, AGENTS.md:7-13
Frontend Conventions (TanStack Start)
The frontend architecture relies on TanStack Router, TanStack Form, and Shadcn UI.
Component and UI Development
Components must prioritize the use of shadcn/ui over raw HTML or other libraries. When creating forms, logic must be abstracted into dedicated components to avoid code duplication. For example, common field error rendering should use a shared <FieldError /> component rather than inlining error logic.
Sources: packages/web/CLAUDE.md:3-7, REVIEW.md:52-78
Form Management and Validation
Forms are managed via @tanstack/react-form and must be validated using Zod.
- Zod as Source of Truth: Zod schemas must be the sole source of truth for types; do not declare separate TypeScript types for form inputs.
- Validation Strategy: Use the form's
validatorAdapterwith Zod. InlineonChangevalidation functions are prohibited. - Schema Sharing: Define Zod schemas once (typically in a feature's schema file) and share them between the client-side form and the server-side function.
Sources: packages/web/CLAUDE.md:9-18, packages/web/src/features/contracts/contracts.functions.ts:13-14
Server Functions and API
All server-side interactions via createServerFn must implement strict input validation.
The diagram shows the standard flow for data validation between the frontend and backend.
- Input Validation: Every
createServerFnmust use.inputValidator(zodSchema). - OpenAPI Integration: The API client is generated from OpenAPI specs. Use
bun run gen:apito updatesrc/api/schema.ts.
Sources: packages/web/CLAUDE.md:21-25, packages/web/src/features/contracts/contracts.functions.ts:27-30
Backend Conventions (.NET)
The backend follows a modular monolith approach with a focus on separation of concerns and dependency injection.
Architectural Structure
The Program.cs file should remain clean by delegating configuration to per-module helper methods. Each module (e.g., Animal, Customer) is responsible for its own service registration and configuration.
| Convention | Description |
|---|---|
| Modular Config | Use builder.Services.Add[Module]Module(configuration) in Program.cs. |
| Configuration | Store connection strings and settings in appsettings.json, not hardcoded. |
| Data Transfer | Use DTOs to expose data; do not expose database entities directly to the API. |
| Error Handling | Implement global exception handling instead of catching exceptions in every endpoint. |
Sources: REVIEW.md:3-50, CHANGELOG.md:8-12
Database and Dependency Injection
Services should be scoped and registered within their respective module extensions. Tightly coupling modules via a shared context (like Common.Counters) is discouraged to allow for future modular separation.
This sequence illustrates the modular registration pattern for services and database contexts.
Sources: REVIEW.md:7-40
File Organization and Routing
The project uses a file-based routing system with specific colocation rules:
- Private Route Files: Files or directories prefixed with
-(e.g.,-components/,-schemas.ts) are excluded from the TanStack Router tree. These are used to colocate route-specific logic. - Feature Directory: Consolidate admin entity logic within the
features/directory to share functionality across routes.
Sources: packages/web/CLAUDE.md:32-35, CHANGELOG.md:27-28, packages/web/src/routes/_authed/admin/contracts/-components/form.tsx:1-10
Testing Standards
Testing requirements differ across the stack:
- Web Package: Skip creating tests for UI components.
- API Package: Tests must focus on business value rather than implementation details. Split tests into separate files for each operation and ensure all variations are tested.
- Coverage: Insufficient coverage is noted as a technical debt item; developers must ensure comprehensive coverage for services.
Sources: packages/web/CLAUDE.md:42, REVIEW.md:41-45
Conclusion
Adhering to these conventions is critical for the success of the Timesheet Zone project. By maintaining descriptive naming, modular backend configuration, and shared Zod validation schemas, the codebase remains robust and adaptable to future requirements.