Files
Khaemhat/docs/ARCHITECTURE.md
Alby96andClaude Opus 5.5 a9eda510f2 feat: postal codes from GeoNames for the ISTAT municipalities (#45)
The municipalities now come with their postal codes, so the lookup from
postal code works on a new company without loading anything. GeoNames
(CC BY 4.0) lists places rather than municipalities: a postal code goes
to a municipality only when the name and the province abbreviation match
exactly one of them (the name alone within Sardinia, whose abbreviations
changed), which covers 7,750 of 7,894 municipalities; the rest are mostly
renamed or merged ones that users complete by hand.

tools/Khaemhat.PlacesTool rebuilds both lists from the ISTAT sheet and
the GeoNames file, framework only, so the yearly update is repeatable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:16:07 +01:00

41 KiB

Architettura di Khaemhat

Stato: bozza · Revisione 2026-11-11 · Fonte: SPEC §1, §2, §3, §4, §5, §7, §9, §13, §15, §19, §21; ADR 0009-0018

Questo documento descrive l'architettura prevista del gestionale: livelli, progetti, regole di dipendenza, composizione dei moduli, gestione multi-database, ciclo di una richiesta e servizi trasversali. Il codice non esiste ancora: ogni sezione indica la milestone (SPEC §20) in cui la parte viene realizzata. Quando il codice cambia questo file va aggiornato nello stesso commit (SPEC §17).

Documenti collegati: DATA-MODEL.md (tabelle), MODULES.md (moduli e licenze), API.md (REST), MCP.md (agenti AI), SPEC.md (specifica normativa), adr/ (decisioni).


1. Principi

Principio Conseguenza pratica Fonte
Un solo runtime: C# 14 su .NET 10 nessun altro linguaggio lato server; JavaScript solo come interop minimo in wwwroot/js SPEC §1.1
Nessuna libreria esterna ammessi solo framework condivisi Microsoft, Npgsql, Microsoft.Data.Sqlite e, nei soli test, Microsoft.NET.Test.Sdk + MSTest; allowlist in Directory.Packages.props verificata da scripts/check-packages.sh SPEC §1.2
Codice indifferente al motore sopra Khaemhat.Data nessuno sa se il database è SQLite o PostgreSQL SPEC §1.3
Un database di sistema + uno per azienda le tabelle operative non hanno company_id SPEC §1.4, §5.4
Configurazione iniziale solo da variabili KHAEMHAT_* nessun file di impostazioni con segreti, scritture solo in KHAEMHAT_DATA_DIR SPEC §1.5, §6
Fiscalità isolata tutto ciò che è italiano vive in Khaemhat.Fiscal.Italy dietro Khaemhat.Fiscal.Abstractions SPEC §1.10
Moduli dietro licenza un modulo non licenziato non registra menu, API, tool MCP né procedure SPEC §1.8, §8
Distribuzione solo Docker unico artefatto: gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione> ADR 0010

2. Livelli e progetti

┌───────────────────────────────────────────────────────────────────────────┐
│ Khaemhat.Web              UI Blazor (Interactive Server) · REST /api/v1 ·  │
│                           MCP /mcp · autenticazione · host · aiuto /help   │
├───────────────────────────────────────────────────────────────────────────┤
│ Khaemhat.Application      casi d'uso per modulo · DTO · permessi ·         │
│                           motore documenti · motore contabile · procedure ·│
│                           automazioni · seeder · report · orchestrazione   │
│                           backup · registro moduli                         │
├──────────────────────────────────────┬────────────────────────────────────┤
│ Khaemhat.Fiscal.Abstractions         │ Khaemhat.Fiscal.Italy              │
│ interfacce paese (IVA, e-invoice,    │ FatturaPA · TD · nature · F24 ·    │
│ calendario, ritenute, cespiti, CEE)  │ LIPE · Intrastat · ritenute ·      │
│                                      │ cespiti · bilancio CEE · SDI       │
├──────────────────────────────────────┴────────────────────────────────────┤
│ Khaemhat.Core             entità · value object · enum · regole di dominio │
│                           · calcoli · validatori · partita doppia          │
├───────────────────────────────────────────────────────────────────────────┤
│ Khaemhat.Infrastructure   cache/Redis (RESP) · crypto · licenze · SMTP/IMAP│
│                           · PDF · XLSX/CSV/ZIP · job · file · backup       │
│                           (pg_dump, S3, WebDAV) · protocollo MCP · HTTP    │
│                           (VIES, BCE, registro pacchetti Gitea, interm.)   │
├───────────────────────────────────────────────────────────────────────────┤
│ Khaemhat.Data             astrazioni DB · query builder · mappe ·          │
│                           migrazioni · unit of work · registro database    │
│   ├─ Khaemhat.Data.Sqlite          └─ Khaemhat.Data.PostgreSql             │
└───────────────────────────────────────────────────────────────────────────┘

Nota: nella figura di SPEC §3 il livello Infrastructure cita "GitHub packages"; per l'emendamento E1 (ADR 0009) il client degli aggiornamenti è GiteaPackagesClient.

2.1 Progetti della soluzione

Progetto Ruolo Milestone
Khaemhat.Core dominio puro: entità, value object (Money, Quantity, Percentage), regole e calcoli, validatori M1 → M10
Khaemhat.Fiscal.Abstractions contratti del pacchetto paese (IFiscalPack, ITaxEngine, IEInvoiceFormat, ISdiTransport, …) M4
Khaemhat.Fiscal.Italy implementazione italiana (ItalyFiscalPack, FatturaPaWriter, F24Exporter, LipeWriter, …) M4 → M10
Khaemhat.Data micro-ORM interno: IDbProvider, ISqlDialect, EntityMap<T>, QueryBuilder<T>, migrazioni M1
Khaemhat.Data.Sqlite provider SQLite (SqliteProvider, SqliteDialect, SqliteWriteLock, SqliteDecimalConverter) M1
Khaemhat.Data.PostgreSql provider PostgreSQL ≥ 16 (PostgresProvider, PostgresDatabaseCreator, PostgresAdvisoryLocks, PostgresPartitioning) M1
Khaemhat.Infrastructure servizi tecnici scritti in casa (cache, crypto, PDF, mail, job, backup, MCP, log) M1 → M12
Khaemhat.Application casi d'uso, moduli (IModule), motore documenti e contabile, seeding, report M2 → M12
Khaemhat.Web host ASP.NET Core 10, Blazor Interactive Server, Minimal API, MCP, autenticazione M0 → M13
tools/Khaemhat.LicenseTool CLI per chiavi ed emissione licenze (chiave privata mai nel repository; non distribuito) M2
tools/Khaemhat.DataModelTool rigenera la sezione generata di docs/DATA-MODEL.md dalle migrazioni (non distribuito, ADR 0018) M1
tools/Khaemhat.PlacesTool rigenera province e comuni del pacchetto italiano dall'elenco ISTAT e dai CAP GeoNames (non distribuito, ADR 0028) M4
tests/* Core, Data, Infrastructure, Fiscal.Italy, Application, Web (MSTest) ogni milestone

3. Regole di dipendenza

Le regole sono verificate da test di architettura in Khaemhat.Core.Tests (SPEC §3, §18): un riferimento non ammesso fa fallire la build di test.

Progetto Può dipendere da Non può dipendere da
Core nulla (solo BCL) qualunque altro progetto
Fiscal.Abstractions Core tutto il resto
Fiscal.Italy Core, Fiscal.Abstractions, Infrastructure (solo XML/PDF/crypto/HTTP) Application, Web, Data.*
Data Core, System.Data.Common provider concreti, Infrastructure, Application
Data.Sqlite Data, Microsoft.Data.Sqlite tutto il resto
Data.PostgreSql Data, Npgsql tutto il resto
Infrastructure Core, Data Application, Web, Fiscal.*, provider concreti
Application Core, Data, Infrastructure, Fiscal.Abstractions Fiscal.Italy, provider concreti, Web
Web Application (e transitivamente il resto); registra in Program.cs i provider concreti e i pacchetti paese —

Altri controlli di architettura (SPEC §18):

  • nessun PackageReference fuori dall'allowlist di Directory.Packages.props;
  • nessun testo dell'interfaccia scritto direttamente nei componenti (tutto passa da ITexts);
  • nessun accesso al pacchetto fiscale se non tramite le interfacce di Fiscal.Abstractions;
  • nessun Process.Start fuori da Infrastructure/Backup (unico uso: pg_dump / pg_restore).
          Web ──────────────► Application ──────► Fiscal.Abstractions ──► Core
           │                    │   │                      ▲
           │ (solo Program.cs)  │   └──► Infrastructure ───┼──► Data ──► Core
           ▼                    ▼            ▲             │
   Data.Sqlite / Data.PostgreSql            │             │
   Fiscal.Italy ────────────────────────────┴─────────────┘

4. Moduli: IModule e ModuleRegistry

Ogni area funzionale è un modulo dentro Khaemhat.Application/Modules/<Nome>/ con struttura fissa (SPEC §4):

Modules/Sales/
├── Services/          casi d'uso (SaleDocumentService, …)
├── Dtos/              record di input/output
├── Validators/        Validator<T> applicativi
├── Migrations/        migrazioni del catalogo azienda (o sistema)
├── Seed/Base/         seeder dati di base
├── Seed/Demo/         seeder dati dimostrativi
├── Reports/           ReportDefinition del modulo
├── Api/               endpoint REST del modulo
├── Mcp/               tool MCP del modulo
├── Procedures/        IProcedure del modulo
├── Permissions.cs     PermissionDefinition del modulo
├── Menu.cs            MenuItem del modulo
└── SalesModule.cs     implementazione di IModule

IModule (in Application.Modules) dichiara, per ogni modulo:

Membro (indicativo) Contenuto
codice licenza (ModuleCode) uno dei 13 codici di SPEC §8.1 (CORE, ACCT, …)
nome, ordine nome localizzato e posizione nel menu
voci di menu (MenuItem) percorso, icona, contatori, permesso richiesto
permessi (PermissionDefinition) codici modulo.entità.azione
migrazioni classi IMigration del catalogo sistema o azienda
seeder ISeeder base e demo
endpoint API mappatura Minimal API sotto /api/v1
tool MCP McpTool registrati in McpToolRegistry
procedure IProcedure per ProcedureCatalog
eventi per le automazioni trigger esposti a TriggerCatalog
sezione di log valore di LogSection
pagine wiki HelpLink verso docs/wiki/<Pagina>.md (F1)

ModuleRegistry enumera i moduli staticamente (nessuna scoperta per riflessione o plugin: SPEC §1.7) e li filtra con LicenseGate in base alle licenze attive. Effetti di un modulo non licenziato (SPEC §8.1): voci di menu nascoste, endpoint API e tool MCP non registrati, procedure non eseguibili, dati conservati; ogni accesso residuo equivale a permesso negato con codice module_not_licensed (ModuleNotLicensedException).

Elenco dei moduli, codici licenza e milestone: MODULES.md.

5. Multi-database

5.1 Database di sistema e database aziendali

Database Nome Contenuto
Sistema khaemhat_system (da KHAEMHAT_SYSTEM_DB) registro aziende, account di istanza (super utente e amministratori), modelli di ruolo, impostazioni, licenze, attività programmate, esecuzioni, politiche e set di backup, log, audit di sicurezza, chiavi DataProtection, chiavi API di istanza, notifiche e sessioni di istanza (tabelle sys_*)
Azienda khaemhat_<codice> (es. khaemhat_demo) tutte le tabelle operative + utenti, ruoli, permessi, sessioni, preferenze, chiavi API, notifiche, allegati, audit, company_profile

Con SQLite ogni database è un file sotto KHAEMHAT_DATA_DIR; con PostgreSQL i database aziendali vengono creati (CREATE DATABASE) sul server indicato da KHAEMHAT_DB_SERVER con un ruolo dotato di CREATEDB. Il dettaglio delle tabelle è in DATA-MODEL.md.

5.2 Contratti principali

Tipo Progetto Responsabilità
IDbProvider Data motore (DbEngine), dialetto, generatore DDL (Ddl), connection string da DatabaseUrl, creazione connessioni, EnsureDatabaseExistsAsync, DatabaseExistsAsync, DropDatabaseAsync, GetServerInfoAsync, IsTransient, EnterWriteScopeAsync (ADR 0018)
ISqlDialect Data quoting, parametri, paginazione, InsertReturningId, Upsert, CaseInsensitiveLike e AdvisoryLock come SqlFragment, conversioni ColumnType
IUnitOfWorkFactory Data CreateAsync(DatabaseScope scope) dove lo scope è System oppure Company(code)
IUnitOfWork / IRepository<T,TKey> Data transazione, repository tipizzati, ExecuteAsync/QueryAsync/StreamAsync su SqlFragment
ICompanyRegistry (CompanyRegistry) Data registra le aziende e risolve companyCode → DatabaseTarget (provider + connection string) decifrando l'URL salvato in sys_companies
ICompanyContext Core (interfaccia), Web (CompanyContextAccessor) azienda corrente: per circuito Blazor e per richiesta API (header X-Company)
SecretProtector Infrastructure AES-256-GCM con chiave derivata da KHAEMHAT_SECRET_KEY per connection string e credenziali

5.3 Risoluzione dell'azienda

  1. Un utente aziendale è vincolato alla propria azienda (scelta nella pagina di accesso, mockup 001).
  2. Un account di istanza (super utente o amministratore) sceglie l'azienda dalla barra superiore (CompanySwitcher) ed entra con permessi completi su di essa.
  3. Un client API indica l'azienda con l'header X-Company: <codice>; una chiave aziendale è già legata a un'azienda (vedi API.md).
  4. ICompanyContext espone il codice; IUnitOfWorkFactory lo usa per aprire il database giusto tramite ICompanyRegistry. Le chiavi di cache sono prefissate con l'azienda (kh:{azienda}:{area}:{key}).
  5. Lo stato dell'azienda in sys_companies (attiva / manutenzione / sola lettura / disattivata) è applicato da MaintenanceMiddleware: in manutenzione gli utenti vengono disconnessi e le API rispondono 503.

5.4 Bootstrap al primo avvio

docker/entrypoint.sh attende il database e avvia l'app; StartupOrchestrator esegue (SPEC §5.4):

  1. validazione delle variabili con KhaemhatOptions.Validate() (termina con messaggio esplicito se manca qualcosa, in particolare KHAEMHAT_SECRET_KEY);
  2. migrazione del database di sistema;
  3. creazione del super utente da KHAEMHAT_SUPERUSER* (solo se sys_users è vuota; cambio password obbligatorio);
  4. creazione della prima azienda da KHAEMHAT_COMPANY_CODE / KHAEMHAT_COMPANY_NAME (CREATE DATABASE o file SQLite), migrazione, tabelle di base (KHAEMHAT_SEED_BASE), dati demo se KHAEMHAT_SEED_DEMO=true;
  5. le variabili di bootstrap vengono rilette solo se la tabella corrispondente è vuota.

6. Flusso di una richiesta

6.1 Interfaccia Blazor (circuito interattivo)

Browser ──HTTP──► Kestrel ──► SecurityHeadersMiddleware ──► TraceIdMiddleware
        ──► CookieSessionAuthenticationHandler (cookie HttpOnly, riga in user_sessions/sys_sessions)
        ──► MaintenanceMiddleware ──► pagina Razor prerender ──► circuito SignalR
Circuito: CurrentUserAccessor + CompanyContextAccessor (azienda del circuito)
        ──► componente pagina (es. SaleDocumentPage) ── code-behind ──► servizio applicativo
        ──► PermissionAuthorizationHandler / [RequirePermission] / LicenseGate
        ──► IUnitOfWorkFactory.CreateAsync(Company(code)) ──► transazione ──► commit
        ──► audit_log · log di sezione · notifiche · invalidazione cache
  • Il circuito verifica la sessione a ogni riconnessione (SPEC §7.3).
  • Nessuna logica nei .razor: code-behind + servizi (SPEC §19). L'interfaccia nasconde ciò che non è permesso, il server verifica sempre.
  • Ogni servizio applicativo è transazionale per operazione; motore documenti e contabile garantiscono atomicità di documento + magazzino + partite + registrazione + numerazione + allegati.

6.2 REST API

Client ──► /api/v1/... ──► TraceIdMiddleware ──► rate limiter per chiave
       ──► ApiKeyAuthenticationHandler (Bearer kh_…, hash SHA-256, IP consentiti, scadenza)
           oppure CookieSessionAuthenticationHandler
       ──► risoluzione X-Company ──► MaintenanceMiddleware (503 se in manutenzione)
       ──► [RequireModule] + [RequirePermission] ──► <Modulo>Endpoints ──► servizio applicativo
       ──► risposta JSON camelCase · ETag · errori RFC 9457 (ProblemDetailsMiddleware) con trace id

Il dettaglio dei contratti HTTP è in API.md; MCP segue lo stesso percorso di autenticazione su /mcp (MCP.md).

7. Servizi trasversali

7.1 Cache (SPEC §9, M2)

  • ICacheProvider: GetAsync, SetAsync (TTL), RemoveAsync, RemoveByPrefixAsync, GetOrCreateAsync, PublishInvalidationAsync.
  • Implementazioni: MemoryCacheProvider (predefinita) e RedisCacheProvider (se KHAEMHAT_REDIS è valorizzata), con client RESP2 scritto in casa (RespClient, RespReader, RespWriter, RedisConnectionPool, RedisSubscriber) su TcpClient/SslStream.
  • Contenuto: tabelle di base, permessi, menu, piano dei conti, listini, licenze, ricerche recenti. Chiavi kh:{azienda}:{area}:{key}.
  • Se Redis cade l'app prosegue in memoria e lo segnala (barra di stato, Stato sistema, log).

7.2 Scheduler (SPEC §9, §12.5; base in M2, attività da UI in M12)

  • JobRunner in-process con CronExpression (sottoinsieme di cron) e JobLock nel database di sistema: ogni attività gira una sola volta anche tra riavvii.
  • Job di sistema: pulizia, verifica licenza, cambi BCE, inbox e canali SDI, coda e-mail, verifica giacenze, backup.
  • Attività programmate degli amministratori (sys_scheduled_tasks): tipi backup, procedura, report via e-mail, notifica, import/export, verifica, script di manutenzione dal catalogo interno (mai shell libera); timeout, retry, notifica esito, storico in sys_job_runs.

7.3 Log (SPEC §9.5, M2)

  • Un solo pipeline ILogger → JsonConsoleFormatter (una riga JSON su stdout) + DbLogSink in sys_log.
  • Ogni modulo scrive nella propria sezione (LogSection, LogSectionScope): Sistema, Autenticazione, Database, Migrazioni, Documenti, Contabilità, Magazzino, SDI/e-invoicing, CRM, Automazioni, Attività programmate, Backup, API/MCP, E-mail/PEC, Integrazioni, UI/circuiti, Prestazioni (SlowQueryLogger: query > 500 ms).
  • Correlazione con trace_id (generato da TraceIdMiddleware): compare negli errori mostrati all'utente ("Codice errore") e nelle risposte API.
  • Retention per livello (errori 365 gg, avvisi 180, info 90, debug 7) e regole di avviso (LogAlertRules).
  • Azioni di sicurezza e di istanza → sys_security_audit (immutabile); modifiche ai dati aziendali → audit_log.

7.4 Pacchetto fiscale (SPEC §1.10, M4 → M10)

  • Application conosce solo Fiscal.Abstractions: IFiscalPack, ITaxEngine, ITaxCodeCatalog, IEInvoiceFormat, IEInvoiceNotificationReader, ISdiTransport, IFiscalReports, IFiscalCalendar, IWithholdingRules, IFixedAssetRules, IFinancialStatementsSchema, IChartOfAccountsTemplate, IIntrastatExporter, ITaxPaymentFormExporter.
  • Program.cs registra ItalyFiscalPack; il pacchetto attivo per un'azienda è scelto da company_profile.country (IT → ItalyFiscalPack). Un altro paese sarà un nuovo progetto Khaemhat.Fiscal.<Paese>.
  • Canali SDI: ISdiTransport con quattro implementazioni (PecSdiTransport, SdiCoopTransport, IntermediaryATransport, IntermediaryBTransport) e SdiRouter per le regole di instradamento.

7.5 Allegati e file generati (SPEC §9.4, M3)

  • Tabella attachments per azienda; un allegato appartiene a un solo documento (entity, entity_id).
  • File su volume: /data/files/<azienda>/<yyyy>/<guid> tramite IFileStore (VolumeFileStore) con quota per azienda; upload in streaming, limite configurabile (25 MB), hook antivirus predisposto.
  • FileGenerationService + GeneratedFileFactory: ogni generazione (PDF, XML FatturaPA, XLSX/CSV, ZIP di cortesia, etichette, estratti conto, rapportini) crea un allegato versionato (v1, v2, …); "Rigenera" crea una nuova versione. Gli XML inviati sono locked.
  • Formati scritti in casa: PdfWriter (con PdfA3Embedder), XlsxWriter/XlsxReader, CsvWriter/CsvReader, ZipStreamWriter. Le stampe massive producono ZIP in streaming, mai file temporanei fuori da /data.

7.6 Backup e ripristino (SPEC §13, M12)

Motore Backup Verifica Ripristino
PostgreSQL PgDumpRunner: pg_dump -Fc --no-owner --no-privileges in streaming verso /data/backups/<db>/bk-<db>-<timestamp>.dump pg_restore --list (BackupVerifier) PgRestoreRunner in khaemhat_restore_<ts> + scambio atomico
SQLite SqliteBackup: VACUUM INTO apertura e integrity_check sostituzione del file in manutenzione
Entrambi backup logico JSON Lines + manifest (LogicalBackupWriter) manifest + hash LogicalBackupReader su database vuoto (anche SQLite → PostgreSQL)
  • Ogni set ha sha256, cifratura AES-256-GCM (BackupEncryptor), copie remote su S3 compatibile (S3Client, SigV4Signer) e WebDAV (WebDavClient); retention GFS (RetentionPolicy); gli allegati dell'azienda sono inclusi.
  • Ripristino: manutenzione → backup di sicurezza → ripristino su database temporaneo → controllo schema e migrazioni → integrità → scambio → fine manutenzione; avviato da un amministratore e confermato dal super utente (notifica + TOTP). Il database di sistema si ripristina solo da CLI (scripts/restore-system.sh) a istanza ferma.

7.7 Sicurezza (SPEC §7, M2)

  • Cookie HttpOnly; Secure; SameSite=Lax, sessioni in tabella (revoca, dispositivi, IP), DataProtection con chiavi in sys_data_protection_keys (DataProtectionDbXmlRepository).
  • Password PBKDF2-SHA256 600.000 iterazioni (PasswordHasher), policy, storico, lockout, TOTP RFC 6238 (TotpGenerator) obbligatorio per account di istanza.
  • Chiavi API kh_… con hash SHA-256 (ApiKeyHasher), prefisso visibile, utente tecnico, permessi propri.
  • Header di sicurezza (SecurityHeadersMiddleware): CSP con nonce, X-Frame-Options: DENY, Referrer-Policy; HSTS dal reverse proxy.

8. Strato dati in breve

  • Micro-ORM interno: mappe esplicite XxxMap : EntityMap<Xxx>, QueryBuilder<T> con un sottoinsieme sicuro di espressioni, il resto come SqlFragment parametrizzato; mai concatenazione di input utente.
  • Optimistic locking su row_version (ConcurrencyException).
  • SQLite: WAL, foreign_keys=ON, busy_timeout=5000, scritture serializzate da SqliteWriteLock, decimali come interi scalati x10⁶.
  • PostgreSQL: pool per database, statement_timeout per sessione, pg_advisory_xact_lock per numeratori, chiusure e scheduler; partizionamento annuale predisposto per le tabelle grandi.
  • Migrazioni in C# con due cataloghi (sistema, azienda) e schema_version per database.

Convenzioni, tipi e tabelle: DATA-MODEL.md.

9. Struttura del repository

Adattata da SPEC §4 con gli emendamenti E1 (Gitea) ed E2 (solo Docker).

Khaemhat/
├── CLAUDE.md                        memoria di progetto ed emendamenti
├── README.md  LICENSE  CHANGELOG.md
├── Khaemhat.sln  global.json  Directory.Build.props  Directory.Packages.props
├── .editorconfig  .gitignore  .dockerignore  .gitattributes
├── assets/                          icon.svg, icon-v1.0.svg, icon-mono.svg, PNG 16-512, favicon.ico
├── deploy/
│   ├── docker-compose.yml           app + postgres + redis (profilo)
│   ├── docker-compose.sqlite.yml    demo autonoma SQLite
│   ├── docker-compose.unraid.yml    etichette net.unraid.docker.*
│   ├── .env.example
│   └── unraid/khaemhat.xml          template Community Applications
├── docker/
│   ├── Dockerfile                   multi-stage, non root, HEALTHCHECK, postgresql-client-17
│   ├── entrypoint.sh                attesa DB, migrazioni di sistema, bootstrap, avvio
│   └── postgres/init.sql
├── .gitea/workflows/
│   ├── ci.yml                       build + test: PR verso main, push su main che toccano codice, tag v*, manuale
│   ├── release.yml                  tag v* e manuale: immagine → registro pacchetti Gitea, release con note
│   └── wiki.yml                     push su main che tocca docs/wiki/**: sincronizza Khaemhat.wiki.git
├── scripts/
│   ├── build.sh  test.sh  run-dev.sh  check-packages.sh  new-migration.sh
│   ├── publish-image.sh             build locale + push nel registro Gitea (alternativa a release.yml)
│   ├── publish-wiki.sh              push di docs/wiki nel wiki Gitea
│   ├── gen-datamodel.sh             genera docs/DATA-MODEL.md dalle mappe
│   ├── restore-system.sh            ripristino del database di sistema a istanza ferma
│   └── seed.sh                      CLI: --base / --demo [--scale N] [--company CODE]
├── src/
│   ├── Khaemhat.Core/               Common/ Entities/ Enums/ Rules/ Validation/ Abstractions/
│   ├── Khaemhat.Fiscal.Abstractions/
│   ├── Khaemhat.Fiscal.Italy/       Vat/ FatturaPa/ Sdi/ Withholding/ F24/ Intrastat/ StampDuty/
│   │                                FixedAssets/ FinancialStatements/ ChartOfAccounts/ Resources/
│   ├── Khaemhat.Data/  Khaemhat.Data.Sqlite/  Khaemhat.Data.PostgreSql/
│   ├── Khaemhat.Infrastructure/     Caching/ Security/ Licensing/ Mail/ Pdf/ Export/ Jobs/ Files/
│   │                                Backup/ Http/ Mcp/ Logging/ Notifications/
│   ├── Khaemhat.Application/        Modules/ Documents/ Ledger/ Automation/ Seeding/ Search/ Audit/
│   │   │                            Backup/ Licensing/
│   │   └── Modules/                 Company/ Parties/ Items/ Sales/ Purchases/ Inventory/ Ledger/ Vat/
│   │                                Assets/ Finance/ EInvoicing/ Crm/ Services/ Channels/ Reports/
│   │                                Admin/ UserSettings/
│   └── Khaemhat.Web/                Program.cs Configuration/ Auth/ Api/ Mcp/ Help/ Components/
│                                    (App, Routes, Layout/, Ui/, Pages/<Modulo>/, Shared/) Localization/ wwwroot/
├── tests/                           Core, Data, Infrastructure, Fiscal.Italy, Application, Web
├── tools/                           Khaemhat.LicenseTool, Khaemhat.DataModelTool, Khaemhat.PlacesTool
└── docs/
    ├── SPEC.md  ARCHITECTURE.md  DATA-MODEL.md  MODULES.md  API.md  MCP.md
    ├── DEPLOY.md  DEVELOPMENT.md  SECURITY.md  STATUS.md
    ├── adr/
    ├── mockups/                     mockup.css, png/ (22 + galleria), thumbs/ (88 miniature), README.md
    └── wiki/                        sorgente della wiki Gitea

Differenze rispetto a SPEC §4: .gitea/workflows/ al posto di .github/workflows/; registro pacchetti Gitea al posto di GHCR; nessun repository khaemhat-assets (icona servita come file raw del repository pubblico); docs/SPEC.md contiene la specifica e CLAUDE.md è breve (ADR 0011); docs/mockups/thumbs/ aggiunta; scripts/restore-system.sh è citato in SPEC §13 e qui riportato nell'albero; è copiato nell'immagine in /app/scripts/ (ADR 0017). Nessun installer né binario distribuito (ADR 0010). In più .vscode/ (debug e attività di Visual Studio Code) e .gitea/scripts/check-yaml.rb (controllo YAML della CI).

Le regole di dipendenza della §3 e l'allowlist dei pacchetti sono verificate da test: Khaemhat.Core.Tests, cartella Architecture/, legge i file di progetto e fallisce su ogni riferimento non ammesso.

10. Classi principali per progetto

Riassunto per area dell'elenco normativo di SPEC §21 (che resta il riferimento completo). Le entità sono elencate in DATA-MODEL.md accanto alle tabelle.

10.1 Khaemhat.Core

Area Classi
Fondamenta Entity<TKey>, IEntity<TKey>, IAuditable, IDemoMarkable, Result/Result<T>, Error, DomainException, ConcurrencyException, ModuleNotLicensedException, Guard
Value object Money, Quantity, Percentage, DiscountFormula
Contesto IClock/SystemClock, ICurrentUser, ICompanyContext, IEventBus, DomainEvent
Entità tabelle azienda, anagrafiche, documenti, contabilità, finanza, e-invoicing, CRM/servizi/canali, utenti aziendali, sistema (vedi DATA-MODEL)
Enum DbEngine, DatabaseScope, UserLevel, ModuleCode, DocumentKind, DocumentStatus, EInvoiceStatus, SdiChannelKind, TaxNature, LogSection, BackupTarget, …
Regole documenti DocumentTotalsCalculator, TaxSummaryBuilder, InstallmentGenerator, StampDutyRule, WithholdingCalculator, SocialSecurityCalculator, PriceResolver, DiscountResolver, StockEffectMatrix, UomConverter
Regole contabili JournalPostingRules, VatSettlementCalculator, ProRataCalculator, DepreciationCalculator, AccrualDeferralCalculator, ExchangeDifferenceCalculator
Regole finanza/CRM AgingCalculator, DunningRules, BankMatcher, LeadScoring
Formati e codici NumberFormatter, DocumentNumberFormat, CodeMaskFormatter
Dashboard TodoAggregator, DoneAggregator, DeadlineAggregator
Validatori ItalianVatNumberValidator, FiscalCodeValidator/FiscalCodeCalculator, IbanValidator, EanValidator, SdiRecipientCodeValidator, EmailValidator, JournalEntryValidator, ChartOfAccountsImportValidator, Validator<T>, ValidationResult

Nota: alcuni validatori di Core hanno nome "italiano" (ItalianVatNumberValidator, FiscalCodeValidator) pur stando fuori dal pacchetto fiscale: è la collocazione indicata da SPEC §21.

10.2 Khaemhat.Fiscal.Abstractions / Khaemhat.Fiscal.Italy

Area Classi
Contratti IFiscalPack, ITaxEngine, ITaxCodeCatalog, IEInvoiceFormat, IEInvoiceNotificationReader, ISdiTransport, IFiscalReports, IFiscalCalendar, IWithholdingRules, IFixedAssetRules, IFinancialStatementsSchema, IChartOfAccountsTemplate, IIntrastatExporter, ITaxPaymentFormExporter
IVA ItalyFiscalPack, ItalianTaxEngine, ItalianTaxCodeCatalog, VatNatures, ReverseChargeRules, SplitPaymentRules, CashVatRules, VatSettlementRules, VatAdvanceCalculator, LipeWriter
FatturaPA FatturaPaWriter, FatturaPaReader, FatturaPaValidator, FatturaPaDocument, FatturaPaCodeLists (con SpecVersion), SdiFileNaming, SdiNotificationParser, P7mExtractor, CadesVerifier
Canali SDI PecSdiTransport, SdiCoopTransport, IntermediaryATransport, IntermediaryBTransport, SdiRouter
Ritenute e F24 WithholdingRulesIt, EnasarcoRules, CuExporter, F24Model, F24Codes, F24Exporter
Intrastat IntrastatModel, IntrastatExporterIt, CombinedNomenclature
Bollo, cespiti StampDutyRulesIt, FixedAssetRulesIt, MinisterialCoefficients
Bilancio CeeSchema2424, CeeSchema2425, FinancialRatios
Piano dei conti e dataset ItalianChartOfAccountsTemplate, ChartOfAccountsCsvFormat, ChartOfAccountsJsonFormat, MunicipalitiesDataset, AbiCabDataset

10.3 Khaemhat.Data e provider

Area Classi
Contratti IDbProvider, ISqlDialect, ISchemaBuilder, IUnitOfWork, IUnitOfWorkFactory, IRepository<,>, Repository<,>, DatabaseUrl, DatabaseTarget, DbProviderCatalog
Registro database ICompanyRegistry, CompanyRegistry, IDatabaseLocator, DatabaseLocator, DatabaseScope, CompanyCodes
Mappe e query EntityMap<T>, ColumnMap, ColumnType, MapRegistry, QueryBuilder<T>, Query<T>, PagedResult<T>, SqlFragment, ExpressionTranslator
Esecuzione UnitOfWork, UnitOfWorkFactory, DataAccessContext (orologio, utente, tentativi), DbExecutor, ReaderMapper, CommandCache, TransientRetryPolicy
Migrazioni IMigration, MigrationAttribute, MigrationRunner, MigrationReport, MigrationCatalog (ForSystem/ForCompany), SchemaVersionStore, SchemaModel, DataModelDocument, TableDefinition, ColumnDefinition, IndexDefinition, ForeignKeyDefinition, DdlGenerator
SQLite SqliteProvider, SqliteDialect, SqliteSchemaBuilder, SqliteWriteLock, SqliteDecimalConverter
PostgreSQL PostgresProvider, PostgresDialect, PostgresSchemaBuilder, PostgresDatabaseCreator, PostgresAdvisoryLocks, PostgresPartitioning, PostgresServerInfo

10.4 Khaemhat.Infrastructure

Area Classi
Cache ICacheProvider, MemoryCacheProvider, RedisCacheProvider, RespClient, RespReader, RespWriter, RedisConnectionPool, RedisSubscriber
Sicurezza PasswordHasher, PasswordPolicy, TotpGenerator, SecureTokenGenerator, ApiKeyHasher, DataProtectionDbXmlRepository, SecretProtector, SecretRotation
Licenze LicenseKey, LicenseDocument, LicenseVerifier, ModuleActivationCode, TestLicenseCatalog, ILicenseActivationService, OfflineActivationService, LicenseMonitor
Mail IMailSender, SmtpMailSender, MailQueue, MailTemplateRenderer, ImapClient, MimeParser
PDF ed export PdfWriter, PdfDocument, PdfPage, PdfFont, PdfTextLayout, PdfImage, PdfA3Embedder, CsvWriter, CsvReader, XlsxWriter, XlsxReader, ZipStreamWriter
Job IJobScheduler, JobRunner, JobDefinition, JobContext, CronExpression, JobLock
File IFileStore, VolumeFileStore, StoredFile, AttachmentStore, GeneratedFileFactory
Backup PgDumpRunner, PgRestoreRunner, SqliteBackup, LogicalBackupWriter, LogicalBackupReader, BackupEncryptor, S3Client, SigV4Signer, WebDavClient, RetentionPolicy, BackupVerifier
HTTP ViesClient, EcbRatesClient, GiteaPackagesClient (al posto di GhcrPackagesClient, ADR 0009), OutboundWebhookClient
MCP McpServer, JsonRpc*, McpTool, McpToolRegistry, McpSchemaGenerator
Log e notifiche DbLogSink, DbLoggerProvider, JsonConsoleFormatter, LogSectionScope, SlowQueryLogger, LogAlertRules, NotificationDispatcher

10.5 Khaemhat.Application

Area Classi
Moduli IModule, ModuleRegistry, ModuleInfo, MenuItem, PermissionDefinition, HelpLink, LicenseGate
Motore documenti DocumentDefinition(s), DocumentService<,>, DocumentFlowService, DocumentFlowWizard, FulfillmentCalculator, DocumentNumberingService, DocumentStateMachine, DocumentCopyService, DeferredInvoicingService, SelfInvoiceService
Contabilizzazione DocumentPostingService, InventoryPoster, InstallmentPoster, LedgerPoster, PostingEngine
Stampa, mail, file DocumentPrintService, IDocumentPrinter, HtmlDocumentPrinter, PdfDocumentPrinter, DocumentMailService, AttachmentService, FileGenerationService
Contabilità JournalService, PeriodLockService, LedgerQueries, PartitarioService, TrialBalanceService, FinancialStatementsService, RecurringEntriesService, ExchangeDifferenceService, ChartOfAccountsImportService, ClosingProcedure/ClosingStep, AccrualDeferralService
IVA e adempimenti VatRegisterService, VatSettlementService, StampDutyService, WithholdingService, IntrastatService, IntentDeclarationService
Cespiti FixedAssetService, DepreciationService
Tesoreria OpenItemService, PaymentService, RemittanceService, SddMandateService, BankStatementImportService, BankReconciliationService, DunningService, CashFlowForecastService, AgingReportService
E-invoicing EInvoiceService, EInvoiceExportService, SdiChannelService, SdiInboxService, SdiNotificationImportService, PurchaseInvoiceImportService, ConservationExportService
CRM LeadService, OpportunityService, PipelineService, ActivityService, CampaignService, TicketService, Party360Service, CrmDashboardService, SalesForecastService
Servizi e canali ContractService, InterventionService, InterventionSchedulingService, ServiceBillingService, IChannelConnector, GenericChannelConnector, ChannelOrderImportService, ChannelSyncService
Report e dashboard ReportDefinition, ReportRunner, ReportCatalog, ScheduledReportService, DashboardService, WidgetCatalog
Amministrazione SystemUserService, UserService, RoleService, PermissionService, SessionService, LicenseService, ModuleActivationService, CompanyService, MaintenanceModeService, DatabaseMaintenanceService, IntegrityCheckService, RebuildService, ScheduledTaskService, BackupService, RestoreService, SystemSettingsService, SecretRotationService, LogQueryService, LogAlertService, SystemStatusService, UpdateCheckService, ApiKeyService, WebhookService
Import ImportWizardService, CsvImportMapper, OpeningBalancesImportService
Automazioni CodeRuleService, CodeSequenceService, AutoFillService, RuleEngine, TriggerCatalog, ConditionEvaluator, ActionExecutor, ProcedureCatalog, IProcedure, ProcedureRunner
Preferenze UserSettingsService, CompanySettingsService
Seeding ISeeder, SeedRunner, SeedContext, BaseDataSeeder/DemoDataSeeder per area, DemoDataRemover
Trasversali GlobalSearchService, AuditTrailService

10.6 Khaemhat.Web

Area Classi
Host Program, KhaemhatOptions, EnvironmentConfigurationReader, StartupOrchestrator, HealthEndpoints, MetricsEndpoint
Middleware MaintenanceMiddleware, TraceIdMiddleware, SecurityHeadersMiddleware, ProblemDetailsMiddleware
Autenticazione e autorizzazione CookieSessionAuthenticationHandler, ApiKeyAuthenticationHandler, SessionStore, CurrentUserAccessor, CompanyContextAccessor, PermissionAuthorizationHandler, RequirePermissionAttribute, RequireLevelAttribute, RequireModuleAttribute, LoginRateLimiter
API e MCP <Modulo>Endpoints, AttachmentEndpoints, OpenApiWriter, ApiDocsPage, McpEndpoint, WebhookEndpoints
Shell App, Routes, MainLayout, TopBar, CompanySwitcher, GlobalSearch, NotificationBell, UserMenu, KhSideMenu, KhTabHost, KhStatusBar
Dashboard Dashboard, DashboardCustomizer, KpiWidget, TodoWidget, DoneTodayWidget, DeadlinesWidget, FulfillmentWidget, RevenueChartWidget, CrmActivitiesWidget, PersonalNotesWidget, ShortcutsWidget, …
Componenti Kh* libreria di SPEC §10.7 (KhIconToolbar, KhDocHead, KhGrid, KhHotlink, KhKanban, KhLogViewer, …)
Pagine generiche DocumentPage<,>, MasterDataPage<T>
Pagine per modulo PartyPage, ItemPage, SaleDocumentPage, PurchaseInvoiceImportPage, JournalEntryPage, VatSettlementPage, EInvoiceDashboard, PipelineBoard, Admin*Page, … (elenco completo in SPEC §21)
Servizi UI ITexts, JsonTextProvider, KeyboardShortcutService, ToastService, DialogService, DrawerService, TabService, PrintService, ThemeService, MenuStateService, HelpService

11. Regole di codice rilevanti per l'architettura (SPEC §19)

  • record per DTO e value object, sealed di default, decimal per importi e quantità (mai double).
  • Date: DateOnly / DateTime UTC; conversione a Europe/Rome solo in presentazione.
  • Async ovunque con CancellationToken; Result<T> per esiti attesi, eccezioni di dominio localizzabili.
  • Validazione in Core/Application: l'interfaccia mostra, non decide.
  • Ogni file appartiene a un modulo; nessuna cartella Utils. Commenti solo per i perché; XML doc sui tipi pubblici di Core, Data, Fiscal.Abstractions.
  • Codice, commenti e commit in inglese; testi dell'interfaccia in italiano tramite Resources/it-IT/*.json.

12. Punti aperti

Punto Nota
Modulo Automation SPEC §4 colloca il motore in Application/Automation/ e non elenca Modules/Automation/; serve comunque un IModule con codice AUTO per filtrare menu e procedure. Da fissare con un ADR in M12.
Sezioni di log per anagrafiche, servizi e report SPEC §9.5 non prevede sezioni dedicate; vedi le proposte in MODULES.md.
Client aggiornamenti GhcrPackagesClient di SPEC §21 è sostituito da GiteaPackagesClient (ADR 0009).