# Architecture Defaults

Read this file when choosing stack, scaffolding a new codebase, or making backend, auth, database, or infrastructure decisions.

## Stack Defaults

- Default to SolidJS for new frontend work.
- Fall back to React when Solid would materially slow delivery, block needed libraries, or fight the existing project.
- Use Vite, TypeScript, and Tailwind CSS on the frontend.
- Prefer Ark UI for Solid and shadcn or shadcn-solid when they fit the project.
- Support responsive layouts, dark and light mode, and accessibility by default.

## Authentication

- Use Better Auth when authentication is required.
- Prefer secure cookie sessions.
- Model user accounts first, then add organizations, teams, roles, or API tokens when the product requires them.

## Backend

- Default to Go for backend services.
- Use Gin for HTTP APIs.
- Use zap for structured logging.
- Keep packages small and focused.
- Avoid framework magic and hidden behavior.
- Keep routing, business logic, and data access explicit.
- Introduce Rust or Python only when the task has a clear technical reason for it.

## API Contract

- Treat OpenAPI as the single source of truth.
- Generate the TypeScript client, shared API types, and request helpers from the OpenAPI spec.
- Do not duplicate API types manually in frontend code.
- Keep request and response shapes aligned with generated artifacts.

## Database

- Use PostgreSQL as the default database.
- Use sqlc for type-safe query generation.
- Use goose for migrations.
- Apply schema changes through versioned migrations only.
- Do not edit production schemas manually.

## Infrastructure

- Make the project runnable with `docker compose up`.
- Use Docker and Docker Compose as the default local orchestration layer.
- Include the application, database, and reverse proxy when the product needs them.
- Use Nginx or Traefik for TLS termination, routing, static file serving, and load balancing.

## Desktop and Mobile

- Use Wails for Go-centric desktop apps. Use Tauri when it is a better technical fit.
- Keep the desktop frontend aligned with the web frontend when possible.
- Use React Native for mobile apps.
- Reuse the same backend APIs and design language across web, desktop, and mobile surfaces.

## Project Layout

Use this structure for greenfield full-stack projects unless the repository already has a better-established layout:

```text
/apps
    /frontend
    /backend

/packages
    /api-client
    /shared-types

/infra
    docker-compose.yml
    nginx
```

Keep frontend and backend concerns clearly separated.

## Code Quality

- Use strict TypeScript.
- Use clear naming and small focused functions.
- Preserve clean module boundaries.
- Favor maintainability and predictability over clever abstractions.