Passa al contenuto principale

Documentazione per Sviluppatori

Guida completa per sviluppatori che vogliono contribuire alla piattaforma Emblema, un ecosistema AI monorepo che combina frontend TypeScript/Next.js con servizi AI basati su Python.

🏗️ Architettura del Sistema​

Emblema è costruito come monorepo con le seguenti componenti principali:

Frontend Applications (/apps)​

  • www-emblema: Applicazione web principale con chat AI, gestione documenti, supporto MCP
  • ui: Libreria di componenti condivisi (Shadcn UI)
  • keycloakify-starter: Tema personalizzato per Keycloak
  • doc-emblema: Documentazione Docusaurus

Backend Services (/apps)​

  • background-task: Worker Celery per operazioni AI intensive (embeddings, TTS, STT, chunking)
  • document-render: Servizio di rendering documenti
  • novu-bridge: Integrazione servizio notifiche
  • mcp-demo: Server demo Model Context Protocol

Infrastruttura​

  • Docker Compose: Stack di servizi containerizzati
  • PostgreSQL: Database principale
  • Milvus: Database vettoriale per ricerca semantica
  • MinIO: Storage oggetti per file
  • Keycloak: Autenticazione e autorizzazione
  • Redis: Cache e broker messaggi
  • Traefik: Reverse proxy e load balancer

🤖 AI-First Development​

Emblema utilizza un approccio di sviluppo innovativo basato su AI-assisted development con Claude Code. Ogni feature, refactoring e miglioramento passa attraverso un workflow strutturato che combina intelligenza umana e artificiale.

Il Workflow: Think → Plan → Code → Review → Document​

Loading diagram...

Comandi Claude Code Specializzati​

Il progetto include comandi personalizzati in .claude/commands/:

  • /think - Brainstorming collaborativo per analisi problema
  • /plan - Creazione piani dettagliati con TODO strutturati
  • /code - Implementazione guidata seguendo i piani
  • /review - Code review AI specializzata
  • /doc-it - Aggiornamento automatico documentazione

🔗 Per dettagli completi: AI-Assisted Development Guide

Benefici dell'Approccio​

  • Velocità: Sviluppo 2-3x più rapido
  • Qualità: -60% bug in produzione
  • Documentazione: Sempre sincronizzata
  • Planning: Piani implementativi dettagliati e tracciabili

📋 Prerequisiti​

Sistema Operativo​

  • Linux/macOS/Windows con WSL2
  • Docker e Docker Compose
  • Node.js 18+ (utilizzare nvm per gestione versioni)
  • Python 3.10+
  • pnpm (package manager)

Strumenti di Sviluppo​

# Installa pnpm globalmente
npm i -g pnpm@8.15.6

# Installa uv per gestione Python (raccomandato)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clona il repository
git clone <repository-url>
cd emblema

🚀 Quick Start​

1. Setup Iniziale​

# Installa dipendenze del monorepo
pnpm install

# Setup ambiente (prima volta)
./install.sh

# Oppure con percorso personalizzato per volumi
EMBLEMA_VOLUME_PATH=/data/emblema ./install.sh

2. Avvio Servizi Base​

# Crea rete Docker
docker network create emblema

# Avvia stack completo
docker compose up -d

# Monitora i log
docker compose logs -f

3. Sviluppo Frontend​

# Avvia applicazione principale in sviluppo
pnpm --filter=www-emblema dev

# Oppure tutti i servizi frontend
pnpm dev

# Solo libreria UI
pnpm --filter=ui dev

4. Sviluppo Backend Python​

# Vai nel servizio specifico
cd apps/background-task

# Installa dipendenze
uv sync

# Avvia in sviluppo
uv run fastapi dev

🔧 Comandi Utili​

Build e Lint​

# Build tutto il monorepo
pnpm build

# Lint e format
pnpm lint
pnpm format

# Type checking
pnpm type-check

Docker Operations​

# Build tutte le immagini
pnpm docker:build

# Export/import immagini
pnpm export-docker-images
pnpm import-docker-images

Generazione Codice​

# Crea nuovo servizio Python
pnpm plop:service

# Crea nuova web app
pnpm plop:web

Sicurezza​

# Scansione vulnerabilità completa
pnpm security:full

# Solo scansione
pnpm security:scan

# Report HTML
pnpm security:report

📚 Guide Dettagliate​

Naviga nelle sezioni seguenti per guide specifiche:

🤝 Supporto​

Per domande e supporto:

  • Crea un issue su GitHub
  • Consulta la documentazione CLAUDE.md per istruzioni AI
  • Riferimenti SECURITY.md per questioni di sicurezza

Questa pagina ti è stata utile?