Guide 10

Development

Contribute to Simmetric Chat: setup, monorepo, scripts, conventions.

Guida per contribuire al codebase: setup, struttura monorepo, script, convenzioni, i18n.

Setup

git clone <repo> && cd simmetric-chat
pnpm install            # installa dipendenze tutti i package
cp .env.example .env    # poi edita JWT_SECRET, COLLECTOR_SECRET, WIDGET_API_KEY
pnpm db:setup           # crea DB + migra + seed admin
pnpm dev                # avvia server/collector/widget/frontend via turborepo

PostgreSQL 16 in locale. pnpm db:setup crea il DB, applica migrazioni Prisma (packages/server/prisma/migrations) e seeda l'admin bootstrap.

Struttura monorepo

pnpm workspaces + Turborepo. 5 package + Tauri:

Package	Porta	Stack	Ruolo
`shared`	—	TS + Zod	Tipi, schema, costanti (leaf, dip solo `zod`)
`server`	3000	Express + Prisma	API, RBAC, agent, RAG FTS/RRF, backup
`collector`	3210	Express	Ingestione, parsing, embedding, vector store
`widget`	3211	Express + Preact IIFE	Widget embeddabile
`frontend`	5173	Vite + React 19 + Tailwind	SPA admin/chat
`src-tauri`	—	Rust + Tauri	Desktop app

Grafo dipendenze: shared ← {server, collector, frontend, widget}. Modularità strict: server↔collector = HTTP only (COLLECTOR_SECRET); widget↔server = API key (X-Api-Key). Nessun import diretto tra server/collector/widget.

Script comuni

Script	Scope	Descrizione
`pnpm dev`	root	Turborepo: avvia tutti i servizi in parallelo
`pnpm build`	root	Build produzione tutti i package
`pnpm lint`	root	ESLint tutti i package
`pnpm typecheck`	root	`tsc --noEmit`
`pnpm test`	root	Jest (unit + integration)
`pnpm test:e2e`	root	Playwright
`pnpm db:setup`	server	Crea DB + migra + seed
`pnpm db:migrate`	server	`prisma migrate dev`
`pnpm db:reset`	server	Reset DB (destructive)
`pnpm i18n:check`	root	Verifica chiavi i18n

Script per-package in packages/<pkg>/package.json. Turborepo cachea output e dipendenze tra task.

Convenzioni di codice

TypeScript strict ovunque; niente any non giustificato.
Zod per validazione input (shared definisce gli schema riutilizzabili).
Prisma come ORM; schema in packages/server/prisma/schema.prisma.
RBAC via middleware: requirePermission, requireAdmin, requireWorkspaceAccess.
Error handling: risposte { error } (400/401/403/404/409/402/429/500); validazione Zod → 400 con details.
SSE per streaming chat (@microsoft/fetch-event-source lato frontend).
Logging: LOG_LEVEL env; usa il logger configurato, non console.log diretto in prod.
Commit: formato Conventional Commits (feat:, fix:, docs:, refactor:...).

Frontend (React 19)

State 3-tier (server-persisted / session / local).
shadcn/ui + Tailwind per l'admin; widget usa Preact + Tailwind, NO shadcn (IIFE bundle).
i18n via hook; file in packages/frontend/src/i18n/locales/.
Shortcut chat: /model (palette Cmd+K), confronto Cmd+Shift+M.

Server (Express)

Route in src/routes/, servizi in src/services/, middleware in src/middleware/.
Agent in src/agent/ (orchestrator.ts, builtinSkills.ts, mcpClient.ts).
Config env in src/config/env.ts (Zod, process.exit(1) se invalide).
OpenAPI via annotazioni @openapi JSDoc → Swagger su /api-docs.

i18n

Lingue con file concreti: en, it, ru. Aggiungi chiavi in tutti e tre i file. pnpm i18n:check verifica completezza.

Discrepanza nota: alcune doc citano "7 languages" ma i file concreti sono en/it/ru. Verifica packages/frontend/src/i18n/locales/ per la lista reale prima di aggiungere traduzioni.

Aggiungere una feature (workflow)

Schema shared — tipi/Zod in packages/shared/src/.
Prisma — modello + migrazione (pnpm db:migrate).
Server — servizio + route + middleware RBAC/license.
Frontend — UI + hook + i18n (en/it/ru).
Test — unit (Prisma mock) + integration (worker DB) + E2E se user-facing.
Docs — aggiorna docs-guide/ e OpenAPI @openapi.

Estensioni comuni

Nuova skill agente: registerSkill in server/src/agent/builtinSkills.ts.
Nuovo endpoint: route in server/src/routes/ + mount in src/index.ts.
Nuovo permesso: PERMISSION_NAMES in shared/src/constants/permissions.ts + ruoli.
Nuovo provider LLM: server/src/services/providerService.ts + preset.
Nuova destinazione backup: implementa IBackupDestinationProvider in server/src/services/backup/providers/.