> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://cla-demo.postmansolutions.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://cla-demo.postmansolutions.com/_mcp/server.

# 1040 Tax Classifier Service

## 📘 Project Overview

**Repository Name:** `poc-autoextract-platform-1040-tax-classifier`

**Purpose:** Automate classification and verification of tax-related PDF documents using Azure Document Intelligence, deployed on Azure Kubernetes Service (AKS) with Spacelift for GitOps-based CI/CD.

\## 🎯 Objective
Build and deploy a scalable, event-driven PDF classification service that:

* Follow the Framework V2 format for all components
* Listens to Azure Service Bus topic `accepted-file`
* Classifies and verifies tax documents using Azure Document Intelligence
* Publishes results to the `classified-file` topic
* Is deployed to Azure Kubernetes Service (AKS) using Spacelift for ADO automation

\## 🧱 System Architecture

```plaintext
+-----------------------------+
|     Azure Service Bus      |
|---------------------------|
| accepted-file (topic)     |
| classified-file (topic)   |
+-------------+-------------+
              |
              v
+-----------------------------+
| Azure Kubernetes Service    |
|-----------------------------|
| Classifier Pod (Node.js)    |
| - Listens to accepted-file  |
| - Classifies PDFs           |
| - Publishes classified-file |
+-------------+---------------+
              |
              v
+-----------------------------+
| Azure Blob Storage          |
| - Original PDFs             |
| - Split PDFs                |
+-------------+---------------+
              |
              v
+-----------------------------+
| Azure Document Intelligence |
| - Classification            |
| - Verification              |
+-----------------------------+
              ▲
              |
+-----------------------------+
|        Spacelift            |
| - ADO CI/CD              |
| - Deploys to AKS            |
| - Monitors ADO repo         |
|   `poc-1040-tax-classifier` |
+-----------------------------+
```

### 🔁 Workflow Summary

1. **Trigger**: A new message is published to the `accepted-file` topic.
2. **Listener**: The Node.js service running in AKS receives the message.
3. **Processing**:
   * Downloads the PDF from Azure Blob Storage.
   * Classifies and verifies it using Azure Document Intelligence.
   * Splits and uploads the resulting PDFs.
4. **Output**: Publishes a message to the `classified-file` topic.
5. **CI/CD**: Spacelift watches the `poc-1040-tax-classifier` repo and deploys changes to AKS automatically.

# 🧩 Low-Level Design

## 📁 Project Structure

```plaintext
    poc-1040-tax-classifier/
    ├── Dockerfile
    ├── package.json
    ├── tsconfig.json
    ├── README.md
    ├── src/
    │   ├── index.ts
    │   ├── listeners/
    │   │   └── acceptedFileListener.ts
    │   ├── orchestrators/
    │   │   └── classifier.ts
    │   ├── services/
    │   │   ├── blobService.ts
    │   │   ├── documentIntelligence.ts
    │   │   ├── pdfProcessor.ts
    │   │   └── serviceBus.ts
    │   ├── models/
    │   │   ├── acceptedFileEvent.ts
    │   │   └── classifiedFileEvent.ts
    │   ├── utils/
    │   │   └── logger.ts
    │   └── config/
    │       └── env.ts
    ├── infra/
    │   └── spacelift/
    │       ├── main.tf
    │       ├── variables.tf
    │       └── kubernetes/
    │           ├── deployment.yaml
    │           ├── service.yaml
    │           └── configmap.yaml
```

## Component Responsibilities

---

| Component                 | Description                                                     |
| ------------------------- | --------------------------------------------------------------- |
| `acceptedFileListener.ts` | Subscribes to `accepted-file` topic and triggers classification |
| `classifier.ts`           | Orchestrates classification, verification, and messaging        |
| `documentIntelligence.ts` | Wraps Azure Document Intelligence SDK                           |
| `pdfProcessor.ts`         | Splits and annotates PDFs using `pdf-lib`                       |
| `blobService.ts`          | Uploads/downloads PDFs from Azure Blob Storage                  |
| `serviceBus.ts`           | Sends messages to `classified-file` topic                       |
| `main.tf`                 | Spacelift-managed Terraform for AKS deployment                  |
| `deployment.yaml`         | Kubernetes deployment manifest for classifier pod               |

# 📬 Message Flow

---

### Incoming Message: `accepted-file`

```
{
  "eventType": "file.accepted",
  "fileId": "43434343-4343-4343-4343-434343434343",
  "internalUrl": "https://azure.blobs.com/internal/43434343.pdf",
  "clientApplicationId": "123e4567-e89b-12d3-a456-426614174000",
  "timestamp": "2025-04-21T14:44:53Z"
}
```

### Outgoing Message: `classified-file`

```
{
  "eventType": "file.classified",
  "fileId": "43434343-4343-4343-4343-434343435555",
  "parentUrl": "https://azure.blobs.com/internal/43434343.pdf",
  "childUrl": "https://azure.blobs.com/internal/434343435555.pdf",
  "clientApplicationId": "123e4567-e89b-12d3-a456-426614174000",
  "classifications": ["1099Gov", "1099NonGov", "Custom"],
```

## 🧪 Testing Strategy

* **Unit Tests**: Jest for all service modules
* **Integration Tests**: Mock Azure SDKs and Service Bus
* **E2E Tests**: Simulate full message flow in AKS dev cluster

---

## 🚀 Deployment

* **CI/CD**: GitHub Actions → Spacelift → AKS
* **Helm**: Used for Kubernetes manifests
* **Spacelift**:
  * Stack: `aks-stack.yaml`
  * Modules: `azure-kubernetes/main.tf`
  * Triggers: GitHub PRs and merges to `main`
  * Secrets: Managed via Spacelift + Azure Key Vault