Struttura Progetto

Guida dettagliata alla struttura del monorepo Emblema e organizzazione del codice.

📂 Struttura Monorepo

emblema/
├── apps/                           # Applicazioni principali
│   ├── www-emblema/               # 🌐 Web app principale (Next.js 14)
│   ├── ui/                        # 🎨 Libreria componenti condivisi
│   ├── doc-emblema/               # 📚 Documentazione (Docusaurus)
│   ├── background-task/           # ⚙️ Worker AI (Python/Celery)
│   ├── document-render/           # 📄 Rendering documenti (Python)
│   ├── novu-bridge/               # 📬 Bridge notifiche (Node.js)
│   ├── mcp-demo/                  # 🤖 Demo MCP server (Python)
│   └── keycloakify-starter/       # 🔐 Tema Keycloak personalizzato
├── packages/                       # Pacchetti condivisi
│   ├── ui/                        # Componenti UI Shadcn
│   └── config/                    # Configurazioni condivise
├── config/                        # Configurazioni infrastruttura
│   ├── traefik/                   # Reverse proxy config
│   ├── keycloak/                  # Auth config
│   └── monitoring/                # Grafana dashboards
├── install/                       # Script installazione
├── scripts/                       # Script utility
│   └── security/                  # Security scanning
├── docker/                        # Dockerfile templates
├── hasura/                        # GraphQL schema & migrations
└── templates/                     # Template generatori codice

🌐 Frontend Applications

apps/www-emblema/

Applicazione web principale con Next.js 14 App Router.

www-emblema/
├── app/                           # Next.js App Router
│   ├── layout.tsx                # Root layout
│   ├── page.tsx                  # Homepage
│   ├── (auth)/                   # Gruppo auth
│   │   ├── login/
│   │   └── register/
│   ├── dashboard/                # Dashboard utente
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── documents/
│   ├── documents/                # Gestione documenti
│   │   ├── [id]/
│   │   ├── upload/
│   │   └── list/
│   ├── chat/                     # Chat AI
│   │   ├── [chatId]/
│   │   └── components/
│   ├── api/                      # API Routes
│   │   ├── v1/                   # API versionate
│   │   ├── auth/[...nextauth]/  # NextAuth
│   │   └── cron/                 # Cron jobs
│   └── settings/                 # Impostazioni utente
├── components/                    # React components
│   ├── ui/                       # UI base components
│   ├── features/                 # Feature components
│   │   ├── document/
│   │   ├── chat/
│   │   ├── chunk/
│   │   └── knowledge-base/
│   └── layout/                   # Layout components
├── hooks/                        # Custom React hooks
├── lib/                          # Utility functions
├── contexts/                     # React contexts
├── schema/                       # Zod validation schemas
├── types/                        # TypeScript types
├── public/                       # Static assets
└── config/                       # App configuration

apps/ui/

Libreria componenti condivisi basata su Shadcn/ui.

ui/
├── src/
│   ├── components/              # Componenti esportati
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── dialog.tsx
│   │   └── ...
│   ├── lib/                     # Utilities
│   └── index.ts                 # Export principale
├── package.json
└── tsconfig.json

⚙️ Backend Services

apps/background-task/

Worker Celery per elaborazioni AI intensive.

background-task/
├── app/
│   ├── __init__.py
│   ├── main.py                  # FastAPI application
│   ├── celery_app.py           # Celery configuration
│   ├── config.py               # Settings
│   ├── dependencies.py         # Dependency injection
│   ├── tasks.py                # Celery tasks
│   ├── chunkers/               # Document chunking
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── document.py         # PDF/TXT chunker
│   │   ├── audio.py            # Audio chunker
│   │   └── video.py            # Video chunker
│   ├── handlers/               # Business logic
│   │   ├── document.py
│   │   ├── audio.py
│   │   ├── storage.py
│   │   └── vector_db.py
│   ├── routers/                # API endpoints
│   │   └── tasks.py
│   └── utils/                  # Utilities
├── tests/                      # Test suite
├── pyproject.toml             # Python dependencies
├── Dockerfile                 # Container config
└── docker-compose.yaml        # Local development

apps/document-render/

Servizio rendering documenti PDF.

document-render/
├── app/
│   ├── main.py                # FastAPI app
│   ├── renderer.py            # Rendering logic
│   └── config.py              # Configuration
├── templates/                 # HTML templates
├── static/                    # CSS/JS assets
└── Dockerfile

🔧 Configuration Files

Root Configuration

emblema/
├── .env.example               # Template variabili ambiente
├── .gitignore                # Git ignore rules
├── docker-compose.yaml        # Compose principale
├── docker-compose-*.yaml      # Compose modulari
├── package.json              # Root package.json
├── pnpm-workspace.yaml       # pnpm workspace config
├── turbo.json                # Turborepo config
└── tsconfig.json             # TypeScript base config

Docker Compose Files

• docker-compose.yaml - File principale con includes
• docker-compose-base.yaml - Servizi base (DB, Redis, MinIO)
• docker-compose-data-source.yaml - Hasura, Milvus
• docker-compose-auth.yaml - Keycloak
• docker-compose-llm.yaml - LiteLLM gateway
• docker-compose-monitoring.yaml - Grafana, Prometheus
• docker-compose-notification.yaml - Novu
• docker-compose-background-task.yaml - Celery workers

📁 Important Directories

/hasura

Schema GraphQL e migrations Hasura.

hasura/
├── metadata/                  # Hasura metadata
│   ├── tables.yaml
│   ├── actions.yaml
│   └── permissions/
├── migrations/               # Database migrations
└── seeds/                   # Seed data

/config

Configurazioni servizi infrastruttura.

config/
├── traefik/
│   ├── traefik.yml         # Config principale
│   ├── traefik-le.yml      # Let's Encrypt config
│   ├── dynamic/            # Routing dinamico
│   └── certs/              # Certificati custom
├── keycloak/
│   └── realm-export.json   # Realm configuration
└── monitoring/
    ├── prometheus.yml      # Prometheus config
    └── dashboards/         # Grafana dashboards

/scripts

Script utility per sviluppo e deployment.

scripts/
├── security/               # Security scanning
│   ├── scan.sh
│   ├── generate-html-report.sh
│   └── generate-sbom.sh
├── export-docker-images.sh # Export per air-gap
├── import-docker-images.sh # Import immagini
└── health-check.sh        # Health monitoring

🏗️ Build Artifacts

Frontend Build

apps/www-emblema/
├── .next/                 # Next.js build output
├── out/                   # Static export (se usato)
└── node_modules/          # Dependencies

Python Services

apps/background-task/
├── .venv/                 # Virtual environment
├── __pycache__/          # Python cache
└── dist/                  # Build artifacts

Docker Images

# Naming convention
emblema/www:dev
emblema/background-task:dev
emblema/document-render:dev

📝 Naming Conventions

File Naming

• Components: PascalCase.tsx (es. DocumentCard.tsx)
• Hooks: camelCase.ts con prefisso use (es. useDocuments.ts)
• Utils: kebab-case.ts (es. format-date.ts)
• Types: kebab-case.types.ts (es. document.types.ts)
• Constants: UPPER_SNAKE_CASE.ts (es. API_ENDPOINTS.ts)

Directory Structure

• Feature-based: Raggruppa per funzionalità
• Colocation: Tieni vicini file correlati
• Shallow nesting: Max 3-4 livelli di profondità

Import Paths

// Usa alias assoluti
import { Button } from "@/components/ui/button";
import { useDocuments } from "@/hooks/use-documents";

// Non path relativi profondi
// ❌ import { Button } from "../../../components/ui/button";

🔒 Security Considerations

Sensitive Files

Non committare mai:

• .env (usa .env.example)
• *.key, *.pem, *.crt
• secrets/, credentials/
• .venv/, node_modules/

Docker Secrets

# docker-compose.yaml
secrets:
  db_password:
    file: ./secrets/db_password.txt

🚀 Development Workflow

1. Setup Locale

# Clone e setup
git clone <repo>
cd emblema
pnpm install
./install.sh

2. Development Mode

# Frontend
pnpm --filter=www-emblema dev

# Backend
cd apps/background-task
uv run fastapi dev

3. Build & Test

# Build all
pnpm build

# Test
pnpm test

# Lint
pnpm lint

📚 Best Practices

1. Monorepo Management

   • Usa pnpm workspace per dipendenze condivise
   • Turbo per build caching
   • Cambia solo ciò che serve

2. Code Organization

   • Feature-based structure
   • Colocate test vicino al codice
   • Shared code in packages/

3. Configuration

   • Environment-specific in .env
   • Defaults in code
   • Type-safe configuration objects

4. Documentation

   • README in ogni app/package
   • Inline comments per logica complessa
   • API documentation con OpenAPI/GraphQL

---

💡 Tip: Usa tree -I 'node_modules|.next|.venv' -L 3 per visualizzare la struttura senza file di build.