mirror of
https://github.com/Dvorinka/SEEN.git
synced 2026-06-03 20:13:02 +00:00
Tomas Dvorak
84 lines
2.7 KiB
Markdown
84 lines
2.7 KiB
Markdown
# 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.
|