# papapaucla/verifactu architecture

> Architecture diagram of the GitHub repository papapaucla/verifactu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/papapaucla/verifactu
- Repository: https://github.com/papapaucla/verifactu

## Overview

##### Project type and purpose
- This is a multi-target .NET class-library ecosystem (“VeriFactu”) that supports invoice generation, hashing, signing, queuing and submission to the Spanish tax authority (AEAT) via VERI*FACTU.
- Targets: .NET Core (cross-platform), .NET Framework (4.0, 4.6.1, 4.7.2) and COM-Interop wrappers for unmanaged clients.
- Key use cases: business-object model of “Invoice” → XML serialization → digital signature (XAdES) → queuing & flow control → REST/SOAP calls to AEAT → blockchain anchoring → QR generation → result retrieval.

##### File structure
- Top-level solution (VeriFactu.sln) contains folders:
- NetCore (Src + Blockchain, Business, Validation, DataStore, Net/Rest & SOAP, XML, QrCode, NoVeriFactu.Signature, Config, Common)
- NetFramework / NetFramework461 / NetFramework472 (class-library projects + Legal & Doc PDFs)
- Interop (three COM assemblies ARM64, x64, x86 + XML COM type libraries in VerifactuLibs)
- Patterns:
- Layered: Business-Logic ↔ DataStore ↔ Transport (REST/SOAP)
- Modular: cross-cutting concerns in Common and Config
- Extension points: IValidator, IJsonSerializer, COM interfaces
- Batch/micro-queue via InvoiceQueue and IntervalWorker
- Deployment: NuGet packages for each target, optional COM registration.

##### Extract architecture insights from README
- Configuration-driven certificate loading (file vs Windows-store).
- Programmatic API (InvoiceEntry, InvoiceCancellation, Blockchain, InvoiceQueue).
- Examples of synchronous calls and long-running queue thread.
- Optional hosted REST-API service (https://facturae…).

##### Components
a. Main system components:
- Client Application(s)
– .NET Core App
– .NET Framework App
– COM-enabled legacy Client
- VeriFactu Library
– Business Model & FlowControl
– Validation Subsystem
– DataStore (inbox/outbox, DocumentBox)
– Transport Layer
- REST/SOAP Client (ApiClient, ApiInvoiceFix)
- JSON Parser & Serializer
- SOAP Envelope/Body abstractions
– Digital Signature Module (NoVeriFactu.Signature)
– XML Serialization (XmlParser, Xml classes under Xml/Factu)
– QR Code Generator
– Blockchain Controller
– Config & Common utilities
- External Systems
– AEAT WebServices (VERI*FACTU endpoints: REST & SOAP)
– Windows Certificate Store / File System (.pfx/.p12)
– Optional Hosted REST API
b. Relationships & data flows:
1. Client → VeriFactu API calls (InvoiceEntry.Save, InvoiceCancellation.Save)
2. VeriFactu Library:
– Build XML business payloads → sign with XAdES (Signature Module)
– Enqueue payloads into InvoiceQueue (FlowControl thread)
– Serialize to JSON or SOAP format → call AEAT endpoint via Transport Layer
– Receive response → update DataStore → return status to Client
– Optionally anchor payload in local Blockchain module
– Provide helpers: GetHashOutput, GetValidateQr
3. External certificate store / file path used by Signature Module
4. AEAT endpoint returns JSON or SOAP → parsed by JSON/SOAP parsers
c. Architectural patterns and design principles
- Layered architecture (Presentation/Client → Service API → Business → Data → Transport → External)
- Dependency injection extension points (IValidator, IJsonSerializer)
- Singletons for configuration and queue management
- Asynchronous queuing with a dedicated worker thread
- Separation of concerns: Signature, XML, Transport, Business, Validation
- Factory/Facade in ApiClient and Blockchain.Get()
d. Key technologies & frameworks
- .NET Standard / .NET Core / .NET Framework
- C# / VB interoperability
- SOAP & REST over HTTP
- Custom JSON parser & serializer
- XAdES digital signature (Microsoft Crypto)
- QRCode generation (pure C#)
- Simple blockchain (in-memory chain via hashes)
- NuGet packaging, MSBuild, GitHub Actions CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Client Applications"
        direction TB
        CoreApp[".NET Core App"]:::client
        FrameworkApp[".NET Framework App"]:::client
        COMAdapter["COM-enabled Legacy Client"]:::com
    end

    %% API Boundary
    API["VeriFactu Library API\n(InvoiceEntry, InvoiceCancellation)"]:::core

    %% Library Modules
    subgraph "VeriFactu Library"
        direction TB
        Business["Business Model"]:::core
        FlowControl["FlowControl\n(InvoiceQueue, IntervalWorker)"]:::core
        Validation["Validation Subsystem"]:::core
        DataStore["DataStore\n(DocumentBox, PeriodInbox/Outbox)"]:::core
        TransportREST["REST Client"]:::core
        TransportSOAP["SOAP Client"]:::core
        Signature["Digital Signature Module"]:::core
        XML["XML Serialization"]:::core
        Qr["QR Code Generator"]:::core
        Blockchain["Blockchain Controller"]:::core
        Config["Config & Common Utilities"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        AEAT["AEAT WebServices\n(REST & SOAP)"]:::external
        CertStore["Certificate Store / File System"]:::external
        HostedAPI["Optional Hosted REST API"]:::external
    end

    %% Relationships
    CoreApp -->|calls| API
    FrameworkApp -->|calls| API
    COMAdapter -->|calls| API
    API --> Business
    Business --> FlowControl
    Business --> Validation
    Business --> DataStore
    Business --> Signature
    Business --> XML
    Business --> Qr
    Business --> Blockchain
    FlowControl --> TransportREST
    FlowControl --> TransportSOAP
    TransportREST -->|HTTP/JSON| AEAT
    TransportSOAP -->|SOAP/XML| AEAT
    Signature --> CertStore
    Blockchain -->|anchor hashes| Blockchain
    API --> HostedAPI
    AEAT --> DataStore
    Validation -->|interfaces| Business

    %% Click Events
    click Business "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/Business"
    click FlowControl "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/Business/FlowControl"
    click Validation "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/Business/Validation"
    click DataStore "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/DataStore"
    click TransportREST "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/Net/Rest"
    click TransportSOAP "https://github.com/papapaucla/verifactu/blob/main/NetCore/Src/Net/Wsd.cs"
    click Signature "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/NoVeriFactu/Signature"
    click XML "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/Xml"
    click Qr "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/Qrcode"
    click Blockchain "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/Blockchain"
    click Config "https://github.com/papapaucla/verifactu/tree/main/NetCore/Src/Config"
    click COMAdapter "https://github.com/papapaucla/verifactu/tree/main/Interop/Verifactu.Com.ARM64/Src/Com/Interop"

    %% Styles
    classDef client fill:#F39C12,stroke:#E67E22,color:#000
    classDef core fill:#27AE60,stroke:#1E8449,color:#fff
    classDef external fill:#3498DB,stroke:#2E86C1,color:#fff
    classDef com stroke-dasharray: 5 5,fill:#F39C12,stroke:#E67E22,color:#000
    class COMAdapter com
    class CoreApp,FrameworkApp client
    class API,Business,FlowControl,Validation,DataStore,TransportREST,TransportSOAP,Signature,XML,Qr,Blockchain,Config core
    class AEAT,CertStore,HostedAPI external
```
