# Three-Level Hierarchy: Complete Guide

## 🎯 The Correct Structure

```
Document Number (PL11089)
    ↓
Transaction Types (Indexing and Scanning, Application of RofO, etc.)
    ↓  
Documents (History Card, Property File, Land Form 7, etc.)
    ↓
PDF View
```

## 📊 Database Structure

### Tables Involved

1. **lr_source_document** - Individual documents
   - `document_number`: PL11089
   - `document_type`: 111, 103, 127
   - `page_count`: 1, 46, 2
   
2. **lr_transaction** - Transaction groupings
   - `transaction_number`: TX-2024-001
   - `transaction_type`: 5, 10, etc.
   
3. **lr_transaction_document** - Links transactions to documents
   - `transaction_id` → `document_id`
   
4. **lr_transaction_metadata** - Transaction type labels
   - `label`: "Indexing and Scanning", "Application of RofO"
   
5. **lr_dictionary** - Document type labels
   - `label`: "History Card", "Property File", "Land Form 7"

### Query Structure

```sql
SELECT 
    t.id AS transaction_id,
    t.transaction_number,
    t.transaction_type,
    tm.label AS transaction_type_label,        -- e.g., "Indexing and Scanning"
    sd.id AS document_id,
    sd.document_type,
    d.label AS document_type_label,             -- e.g., "History Card"
    sd.page_count
FROM lr_source_document sd
LEFT JOIN lr_transaction_document td ON td.document_id = sd.id
LEFT JOIN lr_transaction t ON t.id = td.transaction_id
LEFT JOIN lr_transaction_metadata tm ON tm.Id = t.transaction_type
LEFT JOIN lr_dictionary d ON d.Id = sd.document_type
WHERE sd.document_number = 'PL11089'
ORDER BY t.id, sd.id
```

## 🎨 UI Flow

### Page 1: Enter Document Number
```
┌─────────────────────────┐
│  Enter Document Number  │
│  [  PL11089          ]  │
│  [  Search  ]           │
└─────────────────────────┘
```

### Page 2: View Transactions & Their Documents
```
┌──────────────────────────────────────────────┐
│  Document: PL11089                           │
│                                              │
│  Summary: 2 Transactions, 5 Documents        │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  📋 Transaction: TX-2024-001                 │
│  Indexing and Scanning                       │
│  ─────────────────────────────────────────   │
│  Documents:                                  │
│  📇 History Card (ID: 100...787) 1 page  ←Click│
│  📁 Property File (ID: 100...791) 46 pages ←Click│
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  📋 Transaction: TX-2024-002                 │
│  Application of Right of Occupancy           │
│  ─────────────────────────────────────────   │
│  Documents:                                  │
│  📜 Land Form 7 (ID: 100...800) 2 pages  ←Click│
│  📐 Site Plan (ID: 100...801) 1 page     ←Click│
│  🏆 Certificate (ID: 100...802) 1 page   ←Click│
└──────────────────────────────────────────────┘
```

### Page 3: View PDF
```
┌──────────────────────────────────────────────┐
│  PL11089 • Indexing and Scanning            │
│  Property File • ID: 10000000013791          │
│  ─────────────────────────────────────────   │
│  [            PDF Viewer - 46 pages        ] │
│  [                                         ] │
│  [                                         ] │
└──────────────────────────────────────────────┘
```

## 📝 Example Data

### Input: PL11089

### API Response:
```json
{
  "document_number": "PL11089",
  "total_transactions": 2,
  "transactions": [
    {
      "transaction_id": 123456,
      "transaction_number": "TX-2024-001",
      "transaction_type": 5,
      "transaction_type_label": "Indexing and Scanning",
      "documents": [
        {
          "document_id": 10000000013787,
          "document_type": 111,
          "document_type_label": "History Card",
          "page_count": 1,
          "available_images": 1,
          "has_content": true
        },
        {
          "document_id": 10000000013791,
          "document_type": 103,
          "document_type_label": "Property File",
          "page_count": 46,
          "available_images": 46,
          "has_content": true
        }
      ]
    },
    {
      "transaction_id": 123457,
      "transaction_number": "TX-2024-002",
      "transaction_type": 10,
      "transaction_type_label": "Application of Right of Occupancy",
      "documents": [
        {
          "document_id": 10000000013800,
          "document_type": 127,
          "document_type_label": "Land Form 7 (Right of Occupancy Title)",
          "page_count": 2,
          "available_images": 2,
          "has_content": true
        }
      ]
    }
  ]
}
```

### UI Display:

**Transaction Card 1:**
```
┌───────────────────────────────────────┐
│ 📋                                    │
│ Transaction: TX-2024-001              │
│ Indexing and Scanning                 │
│ Document: PL11089                     │
│                                       │
│ Documents: 2    Total Pages: 47       │
│ ─────────────────────────────────────  │
│ 📄 Documents:                         │
│                                       │
│ 📇 History Card                       │
│    ID: 10000000013787                 │
│    1 page, 1 image               ←Click│
│                                       │
│ 📁 Property File                      │
│    ID: 10000000013791                 │
│    46 pages, 46 images           ←Click│
└───────────────────────────────────────┘
```

**Transaction Card 2:**
```
┌───────────────────────────────────────┐
│ 📋                                    │
│ Transaction: TX-2024-002              │
│ Application of Right of Occupancy     │
│ Document: PL11089                     │
│                                       │
│ Documents: 1    Total Pages: 2        │
│ ─────────────────────────────────────  │
│ 📄 Documents:                         │
│                                       │
│ 📜 Land Form 7                        │
│    ID: 10000000013800                 │
│    2 pages, 2 images             ←Click│
└───────────────────────────────────────┘
```

## 🔄 User Interaction Flow

```
User enters "PL11089"
    ↓
Backend Query:
    - lr_source_document (find documents with document_number = PL11089)
    - lr_transaction_document (find which transactions own these documents)
    - lr_transaction (get transaction details)
    - lr_transaction_metadata (get transaction type labels)
    - lr_dictionary (get document type labels)
    ↓
Returns grouped structure:
    Transaction 1
        ├── Document A
        └── Document B
    Transaction 2
        └── Document C
    ↓
UI displays transaction cards
    Each card shows:
        - Transaction number & type
        - List of documents
    ↓
User clicks "Property File" document
    ↓
Backend fetches PDF for that specific document_id
    ↓
Display PDF in viewer
```

## 🎯 Key Points

### 1. **Hierarchy Levels**
- **Level 1**: Document Number (e.g., PL11089) - Property identifier
- **Level 2**: Transaction Type (e.g., "Indexing and Scanning") - Process/workflow grouping
- **Level 3**: Document (e.g., "Property File") - Actual file/document

### 2. **Why This Structure?**
- One property (PL11089) can have multiple transactions
- Each transaction can involve multiple documents
- Different transaction types represent different workflows:
  - "Indexing and Scanning" - Initial document capture
  - "Application of RofO" - Right of Occupancy application
  - "Title Registration" - Title deed registration
  - etc.

### 3. **Database Relationships**
```
document_number (PL11089)
    ↓ (1 to many)
transactions (TX-2024-001, TX-2024-002)
    ↓ (many to many via junction table)
documents (History Card, Property File, Land Form 7)
    ↓ (1 to many)
images (.bin or .pdf files in contentstore)
```

## 🚀 Testing

### 1. Test the API
```bash
curl "http://localhost:8001/documents/by-document-number-enhanced?document_number=PL11089" | jq
```

**Expected Output**:
```json
{
  "document_number": "PL11089",
  "total_transactions": 2,
  "transactions": [
    {
      "transaction_id": 123456,
      "transaction_type_label": "Indexing and Scanning",
      "documents": [...]
    },
    {
      "transaction_id": 123457,
      "transaction_type_label": "Application of RofO",
      "documents": [...]
    }
  ]
}
```

### 2. Test the UI
```bash
# 1. Open UI
http://localhost:8080/index_v2.html

# 2. Enter: PL11089

# 3. See transaction cards grouped by type

# 4. Click on a document within a transaction

# 5. View PDF
```

## 📊 Complete Example

```
Input: PL11089

Output:
┌─────────────────────────────────────────────┐
│ Transaction: Indexing and Scanning          │
│ ├── History Card (1 page)                   │
│ └── Property File (46 pages)                │
│                                             │
│ Transaction: Application of RofO            │
│ └── Land Form 7 (2 pages)                   │
└─────────────────────────────────────────────┘

User clicks "Property File"
    ↓
Shows: 46-page PDF of the property file document
```

## 🎨 Visual Summary

```
DOCUMENT NUMBER
    PL11089
        │
        ├─ TRANSACTION #1: Indexing and Scanning
        │       ├─ History Card (ID: ...787)
        │       └─ Property File (ID: ...791)
        │
        └─ TRANSACTION #2: Application of RofO
                └─ Land Form 7 (ID: ...800)
```

---

**All three levels are now properly displayed!** 🎉