# TaxCore Architecture Diagrams

## Current Architecture (After Implementation)

```
┌──────────────────────────────────────────────────────────────────────┐
│                           Web Browser                                 │
│                                                                        │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │                  POS Interface (POS.js)                         │  │
│  │  - Cart Management                                              │  │
│  │  - Product Selection                                            │  │
│  │  - Payment Processing                                           │  │
│  │  - Customer Selection                                           │  │
│  └────────────┬─────────────────────────────┬─────────────────────┘  │
│               │                              │                        │
│               │ localStorage:                │ localStorage:          │
│               │ taxcore_direct = true        │ taxcore_direct = false │
│               │                              │                        │
└───────────────┼──────────────────────────────┼────────────────────────┘
                │                              │
                │ Direct Mode                  │ Proxy Mode
                │ (Better Performance)         │ (More Secure)
                │                              │
                ▼                              ▼
┌───────────────────────────┐    ┌─────────────────────────────────────┐
│   Node.js TaxCore Service │◄───┤  Apache/PHP Web Server              │
│   (taxcore-service.js)    │    │                                     │
│                           │    │  ┌──────────────────────────────┐  │
│   Port: 3001              │    │  │  PosController.php           │  │
│                           │    │  │  - taxcore()                 │  │
│   Endpoints:              │    │  │  - getTaxRates()             │  │
│   • GET  /health          │    │  │  - callTaxCoreService()      │  │
│   • GET  /tax-rates       │    │  └──────────────────────────────┘  │
│   • POST /sale            │    │                                     │
│                           │    └─────────────────────────────────────┘
│   Features:               │
│   • PFX Certificate       │
│   • curl Integration      │
│   • Auto-discovery        │
│   • All Sale Types        │
└───────────┬───────────────┘
            │
            │ mTLS (Mutual TLS)
            │ PFX Certificate + Password
            │ via curl --cert-type P12
            │
            ▼
┌───────────────────────────────────────────────────────────────────────┐
│              Fiji Revenue & Customs Service (FRCS)                    │
│                      TaxCore API (V-SDC)                              │
│                                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │  API Endpoints:                                                  │ │
│  │  • POST /v3/invoices  - Create sales (Normal, Advance, etc.)    │ │
│  │  • POST /v3/pin       - PIN authentication                       │ │
│  │  • GET  /v1/tax-rates - Fetch tax rates                          │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  Returns:                                                              │
│  • Invoice Number                                                      │
│  • Journal (Receipt)                                                   │
│  • QR Code                                                             │
│  • Verification URL                                                    │
│  • Digital Signature                                                   │
└────────────────────────────────────────────────────────────────────────┘
```

## Data Flow Diagram

### Sale Transaction Flow

```
1. User adds items to cart
         │
         ▼
2. User clicks "Pay" button
         │
         ▼
3. POS.js prepares sale data
   ├─ Line items
   ├─ Payments
   ├─ Customer info
   ├─ Cashier info
   └─ Sale type
         │
         ▼
4. sendTaxCoreData(saleData)
   │
   ├─────────────┬────────────┐
   │ Direct Mode │ Proxy Mode │
   │             │            │
   ▼             ▼            │
   Node.js ◄───── PHP ────────┘
   Service        Proxy
   (3001)
   │
   ▼
5. Enrich payload
   ├─ Add DateAndTimeOfIssue
   ├─ Add invoiceType
   ├─ Add Options
   └─ Set transactionType
         │
         ▼
6. Execute curl with PFX cert
   POST to TaxCore API
         │
         ▼
7. TaxCore processes and returns
   ├─ Invoice Number
   ├─ Journal (receipt text)
   ├─ QR Code
   ├─ Tax breakdown
   └─ Digital signature
         │
         ▼
8. Node.js returns to caller
   (browser or PHP)
         │
         ▼
9. Save to database
   ├─ sales_receipts table
   └─ lineitems_payments table
         │
         ▼
10. Display receipt to user
    ├─ Print via QZ Tray
    └─ Show on screen
```

## Component Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                      TAF ERP System                              │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend   │    │   Web Server     │    │   Node.js       │
│              │    │                  │    │   Services      │
│  • HTML/CSS  │    │  • Apache        │    │                 │
│  • JavaScript│◄───┤  • PHP 8.x       │◄───┤  • WebSocket    │
│  • POS.js    │    │  • Controllers   │    │  • TaxCore      │
│  • IndexedDB │    │  • APIs          │    │  • Redis        │
└──────────────┘    └──────────────────┘    └─────────────────┘
                              │                     │
                              ▼                     ▼
                    ┌──────────────────┐    ┌─────────────────┐
                    │   PostgreSQL     │    │   Redis         │
                    │   Database       │    │   Cache/PubSub  │
                    └──────────────────┘    └─────────────────┘
```

## Certificate Flow

```
┌──────────────────────────────────────────────────────────────────┐
│                 TaxCore Certificate Handling                      │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  Environment Var │
                    │  TAXCORE_PFX_PATH│
                    └─────────┬────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │ resolveCertPath()│
                    │  Auto-discovery  │
                    └─────────┬────────┘
                              │
            ┌─────────────────┼─────────────────┐
            │                 │                 │
            ▼                 ▼                 ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │ Explicit     │  │ Project      │  │ System       │
    │ Path         │  │ Directory    │  │ Directory    │
    │              │  │ TAF/FRCS_... │  │ /var/www/... │
    └──────────────┘  └──────────────┘  └──────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  Certificate     │
                    │  File Found?     │
                    └─────────┬────────┘
                              │
                    ┌─────────┴─────────┐
                    │ YES               │ NO
                    ▼                   ▼
            ┌──────────────┐    ┌──────────────┐
            │  Use for     │    │  Error:      │
            │  curl --cert │    │  Cert not    │
            │  --cert-type │    │  found       │
            │  P12         │    └──────────────┘
            └──────────────┘
```

## Sale Type Matrix

```
┌──────────────┬─────────────────┬──────────────────┬─────────────┐
│  Sale Type   │  invoiceType    │  Typical Use     │  Payment    │
├──────────────┼─────────────────┼──────────────────┼─────────────┤
│  Normal      │       0         │  Regular sale    │  Full       │
│  Proforma    │       1         │  Quote/estimate  │  Zero       │
│  Copy        │       2         │  Duplicate       │  Any        │
│  Training    │       3         │  Testing/demo    │  Any        │
│  Advance     │       4         │  Deposit/prepay  │  Partial    │
└──────────────┴─────────────────┴──────────────────┴─────────────┘
```

## Connection Modes Comparison

```
┌─────────────────────┬──────────────────┬─────────────────────┐
│     Feature         │  Direct Mode     │   Proxy Mode        │
├─────────────────────┼──────────────────┼─────────────────────┤
│  Performance        │  ★★★★★ Best      │  ★★★★☆ Good         │
│  Security           │  ★★★★☆ Good      │  ★★★★★ Better       │
│  Setup Complexity   │  ★★★☆☆ Moderate  │  ★★★★☆ Easier       │
│  Network Hops       │  2 (Browser→Node)│  3 (Browser→PHP→Node│
│  Auth Integration   │  ★★★☆☆ Separate  │  ★★★★★ Integrated   │
│  Debugging          │  ★★★★★ Easier    │  ★★★☆☆ More steps   │
│  Scalability        │  ★★★★★ Better    │  ★★★★☆ Good         │
│  Recommended For    │  High volume     │  Regular use        │
└─────────────────────┴──────────────────┴─────────────────────┘
```

## Error Handling Flow

```
Sale Request
    │
    ▼
┌─────────────────────────┐
│  Validate Request       │
│  - Items present?       │
│  - Payments valid?      │
│  - Customer info?       │
└──────────┬──────────────┘
           │
    ┌──────┴──────┐
    │ Valid?      │
    └──────┬──────┘
           │ NO
    ┌──────┴──────────────┐
    │ Return 400 Error    │
    │ Invalid Request     │
    └─────────────────────┘
           │ YES
           ▼
┌─────────────────────────┐
│  Check Certificate      │
│  - File exists?         │
│  - Readable?            │
│  - Password correct?    │
└──────────┬──────────────┘
           │
    ┌──────┴──────┐
    │ Valid?      │
    └──────┬──────┘
           │ NO
    ┌──────┴──────────────┐
    │ Return 500 Error    │
    │ Certificate Error   │
    └─────────────────────┘
           │ YES
           ▼
┌─────────────────────────┐
│  Call TaxCore API       │
│  - Enrich payload       │
│  - Execute curl         │
│  - Parse response       │
└──────────┬──────────────┘
           │
    ┌──────┴──────┐
    │ Success?    │
    └──────┬──────┘
           │ NO
    ┌──────┴──────────────┐
    │ Return 500 Error    │
    │ API Call Failed     │
    │ + Error Details     │
    └─────────────────────┘
           │ YES
           ▼
┌─────────────────────────┐
│  Save to Database       │
│  - sales_receipts       │
│  - lineitems_payments   │
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│  Return Success         │
│  - Receipt              │
│  - Invoice Number       │
│  - QR Code              │
└─────────────────────────┘
```

## Deployment Architecture

```
Production Environment
─────────────────────────

┌──────────────────────────────────────────────────────┐
│                   Load Balancer                       │
│                  (nginx/Apache)                       │
└───────────────────────┬──────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
        ▼               ▼               ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Web Server  │ │  Web Server  │ │  Web Server  │
│  Instance 1  │ │  Instance 2  │ │  Instance 3  │
│  (PHP)       │ │  (PHP)       │ │  (PHP)       │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │                │                │
       └────────────────┼────────────────┘
                        │
                        ▼
        ┌───────────────────────────────┐
        │   Node.js TaxCore Service     │
        │   (PM2 Cluster Mode)          │
        │                               │
        │   ┌─────────┐  ┌─────────┐   │
        │   │Instance │  │Instance │   │
        │   │   1     │  │   2     │   │
        │   └─────────┘  └─────────┘   │
        └───────────┬───────────────────┘
                    │
                    ▼
        ┌───────────────────────────────┐
        │     TaxCore API (FRCS)        │
        │     External Service          │
        └───────────────────────────────┘
```

## Monitoring Stack

```
┌──────────────────────────────────────────────────────┐
│                Application Layer                      │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐    │
│  │ POS        │  │ PHP        │  │ Node.js    │    │
│  │ Frontend   │  │ Backend    │  │ TaxCore    │    │
│  └──────┬─────┘  └──────┬─────┘  └──────┬─────┘    │
│         │               │               │           │
│         └───────────────┼───────────────┘           │
│                         │                           │
└─────────────────────────┼───────────────────────────┘
                          │
                          │ Logs & Metrics
                          ▼
┌──────────────────────────────────────────────────────┐
│              Monitoring & Logging                     │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐    │
│  │ PM2        │  │ Log Files  │  │ Error      │    │
│  │ Dashboard  │  │ (tail -f)  │  │ Tracking   │    │
│  └────────────┘  └────────────┘  └────────────┘    │
└──────────────────────────────────────────────────────┘
```

---

**Legend:**
- `◄─►` : Bidirectional communication
- `───►` : Unidirectional flow
- `┌───┐` : Component/Service
- `▼`    : Process flow direction