SEEN/.blackbox/skills/tdvorak-fullstack/references/architecture.md

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:

/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.