Configuration & Secrets Management
Relevant source files
The following files were used as context for generating this wiki page:
Configuration and secrets management in this project is handled through a combination of environment variables, JSON configuration files, and code-based module extensions. The architecture ensures that sensitive information, such as database connection strings and OAuth secrets, are managed externally or via structured configuration objects to maintain security and modularity.
The system is split between the .NET backend and the TanStack Start frontend. The backend utilizes standard .NET configuration patterns enhanced by modular helper methods, while the frontend employs a strictly validated schema for server-side environment variables.
Frontend Configuration & Environment Variables
The frontend utilizes a centralized environment variable management system located in packages/web/src/env.server.ts. This system uses the Zod library to define a strict schema for all required server-side variables. If any variables are missing or invalid, the process terminates immediately during startup to prevent runtime failures.
Environment Schema Validation
The environment validation ensures that critical URLs and authentication secrets are present before the application starts.
The diagram shows the synchronous validation flow for environment variables during the web package initialization.
Sources: packages/web/src/env.server.ts:3-19
Required Environment Variables
| Variable | Type | Description | Default |
|---|---|---|---|
SERVER_URL | URL | The base URL of the backend API. | None (Required) |
APP_BASE_URL | URL | The base URL of the frontend application. | http://localhost:3000 |
AUTH_TENANT_ID | String | Microsoft Entra ID Tenant ID for OAuth. | None (Required) |
AUTH_CLIENT_ID | String | Microsoft Entra ID Client ID. | None (Required) |
AUTH_CLIENT_SECRET | String | Secret key for the OAuth Client. | None (Required) |
AUTH_SECRET | String | General secret for auth session management. | None (Required) |
Sources: packages/web/src/env.server.ts:3-11
Backend Configuration & Modularization
The .NET API architecture emphasizes "Separation of Concerns" by moving configuration responsibility to individual modules. Instead of a monolithic Program.cs, the project uses extension methods to inject configuration into specific functional areas.
Module Configuration Pattern
Modules define their own configuration records and keys. For example, a CustomerModule would use a CustomerConfig record with a specific key to retrieve its settings from appsettings.json.
The diagram illustrates how configuration is delegated from the main entry point to specific extension methods.
Sources: packages/api/Program.cs:17-26, REVIEW.md:27-44
Best Practices & Refactorings
Recent architectural improvements have focused on removing hardcoded strings and improving maintainability:
- Connection Strings: Moved from hardcoded values in
Program.cstoappsettings.json. - Global Exception Handling: Shifted from manual try-catch blocks in services to a global handler returning standard error responses.
- JSON Serialization: Configured via
AddTszJson()andConfigureHttpJsonOptionsto enforce strict number handling and schema transformations for OpenAPI.
Sources: REVIEW.md:5-25, CHANGELOG.md:8-10, packages/api/Program.cs:15-18
Secrets and Security Management
The project implements several layers of security to protect configuration data:
- OAuth with Entra ID: Authentication secrets are managed via environment variables on the web server and injected via
builder.AddEntraJwtAuth()on the API. - Linting for Secrets: The project utilizes
eslint-plugin-no-secretsin the rootpackage.jsonto prevent accidental commits of sensitive data in the frontend codebase. - Environment Validation: As seen in
env.server.ts, secrets likeAUTH_CLIENT_SECRETare validated for a minimum length of 1 character to ensure they are not empty.
Sources: packages/web/src/env.server.ts:9-11, package.json:28, CHANGELOG.md:9
Build & Tooling Configuration
The monorepo uses different tools to manage the build and development environment configuration across packages.
| Feature | Tool / Configuration File | Description |
|---|---|---|
| Monorepo Manager | bun | Specified in root packageManager and used for all scripts. |
| Frontend Bundler | Vite | Configured in packages/web/vite.config.ts with TanStack Start plugins. |
| Path Aliases | tsconfig.json | Managed via tsconfigPaths: true in Vite and imports in package.json. |
| API Client Gen | openapi-typescript | Script gen:api generates types from the API's OpenAPI JSON endpoint. |
Sources: package.json:34, packages/web/vite.config.ts:10-12, packages/web/package.json:5-7, 18
Summary
Configuration in this project is characterized by strict validation and modularity. By leveraging Zod for frontend environment variables and .NET extension methods for backend service configuration, the system maintains a high degree of technical accuracy and prevents common deployment errors related to missing secrets or malformed connection strings.