📘 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

+-----------------------------+
|     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

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

🧩 Low-Level Design

📁 Project Structure

    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