Conventions

Consistency helps teams ship code faster and keep maintenance costs low. By following strict code conventions, we keep code simple and make onboarding easy for new developers.

Vertical Module Boundaries

The most important rule in this template is the separation of business modules:

• Domain Colocation: Store UI components, server actions, settings, and business logic inside the module directory (e.g. src/modules/ai/).
• No Cross-Module Imports: Code inside src/modules/ai/ must not import directly from src/modules/auth/.
• Shared Promotion: If code is needed by multiple modules, move it to src/modules/shared/ or promote it to a generic utility inside the src/shared/ layer.

graph LR
  subgraph Modules Layer
    AI[modules/ai]
    Auth[modules/auth]
    SharedMod[modules/shared]
  end
  subgraph Shared Core
    Tech[src/shared]
  end
  AI --> SharedMod
  Auth --> SharedMod
  AI -.-> |FORBIDDEN DIRECT IMPORT| Auth
  AI --> Tech
  Auth --> Tech

Environment Config & Safety

To prevent runtime errors, never call process.env or import.meta.env directly in your components. Instead, validate all environment configurations at startup:

import { z } from 'zod'

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  VITE_ENABLED_MODULES: z.string().optional(),
  AI_PROVIDER: z.enum(['openai', 'anthropic', 'ollama']).default('ollama')
})

export const env = envSchema.parse(import.meta.env)

Route Colocation Rules

We use TanStack Router for file-based routing. Keep route files thin and delegate layout rendering to components inside your module directories:

1. Define routes under src/routes/.
2. Import the page view or layout component from your module directory.
3. Avoid writing complex UI code directly inside the route files.

Testing Conventions

We run automated tests to maintain type safety and application reliability:

• Unit & Component Tests: Run with Vitest (pnpm test:unit). Keep test files colocated with their target component using the .spec.ts suffix.
• E2E Browser Tests: Run with Playwright (pnpm test:e2e). Store these tests under tests/e2e/ to test user authentication and AI generation flows.