# Aumentum Browser Access System - Complete Summary

## 🎯 What We Built

A complete **browser-accessible API** for Aumentum Registry that converts `.bin` files (LEADTOOLS JPEG) to PDF and serves them via REST endpoints, bypassing the deprecated Silverlight requirement.

## ✅ Completed Features

### 1. **Database Integration**
- ✅ MSSQL support for LRS43 database
- ✅ Query `LRSAdmin` schema tables
- ✅ Discover tables automatically
- ✅ Connection logging and debugging

### 2. **Document Resolution**
- ✅ Resolve `store://` URLs to filesystem paths
- ✅ Query `alf_node_properties` by document_number
- ✅ Join `alf_node` → `alf_content_data` → `alf_content_url`
- ✅ Support multiple storage formats (JPEG/PDF)

### 3. **PDF Conversion**
- ✅ Convert LEADTOOLS `.bin` to PDF using PIL
- ✅ Preserve timestamps and metadata
- ✅ Validate JPEG magic bytes
- ✅ On-demand conversion

### 4. **REST API Endpoints**
- ✅ `GET /health` - Health check
- ✅ `GET /schema` - Discover database schema
- ✅ `GET /lrs/source-documents` - Recent source documents
- ✅ `GET /lrs/content/recent` - Recent Alfresco content
- ✅ `GET /documents/by-document-number?document_number=BP3208` - Resolve content URLs
- ✅ `GET /documents/pdf-by-document-number?document_number=BP3208` - Stream PDF
- ✅ `GET /documents/pdf-by-store-url?store_url=store://...` - Convert by URL
- ✅ `GET /docs` - Interactive API documentation

### 5. **Browser Extension**
- ✅ Chrome/Edge extension skeleton
- ✅ Popup UI for document lookup
- ✅ API integration ready
- ✅ PDF viewing support

### 6. **Windows Deployment**
- ✅ Complete deployment guide
- ✅ ODBC driver setup instructions
- ✅ Windows Service integration guide
- ✅ Troubleshooting documentation
- ✅ Automated batch scripts

## 📁 Files Created

### Core Application
- `aumentum_browser_service.py` - Service layer (512 lines)
- `aumentum_api.py` - FastAPI REST API (271 lines)
- `convert_script_db.py` - Database-backed conversion (273 lines)
- `requirements.txt` - Dependencies

### Configuration & Scripts
- `START_API.sh` / `STOP_API.sh` - Server control
- `test_db_connection.py` - DB connectivity test
- `test_all_endpoints.sh` - API endpoint tests
- `deploy_windows.bat` - Windows installer

### Documentation
- `README.md` - Main documentation
- `README_BROWSER_ACCESS.md` - Browser access guide
- `AUMENTUM_DATA_STRUCTURES.md` - Database schema documentation
- `DEPLOYMENT_WINDOWS.md` - Windows deployment guide
- `WINDOWS_SERVER_2012_OPTIONS.md` - Migration strategies
- `QUICKSTART_BROWSER.md` - Quick start guide

### Browser Extension
- `browser_extension/manifest.json` - Extension config
- `browser_extension/popup.html` - UI
- `browser_extension/popup.js` - Logic

## 🔗 How It Works

```
Browser Request (document_number=BP3208)
    ↓
FastAPI Endpoint: /documents/pdf-by-document-number
    ↓
Service Layer: resolve_store_urls_by_document_number()
    ↓
MSSQL Query: 
    - Query alf_node_properties WHERE string_value = 'BP3208'
    - Join to alf_node, alf_content_data, alf_content_url
    - Get store:// URL
    ↓
Parse: store://2014/12/18/16/20/e03a480a...bin → filesystem path
    ↓
Convert: .bin (LEADTOOLS JPEG) → .pdf using PIL
    ↓
Serve: Stream PDF to browser
```

## 🚀 Quick Start

### On Windows Server

```powershell
# 1. Install dependencies
.\PLAGIS_AUMENTUM\deploy_windows.bat

# 2. Configure database (edit aumentum_browser_service.py)
# Set: server, database, username, password, contentstore path

# 3. Install ODBC Driver
# Download from Microsoft

# 4. Test connection
python PLAGIS_AUMENTUM\test_db_connection.py

# 5. Start server
python PLAGIS_AUMENTUM\aumentum_api.py
```

### On macOS/Linux

```bash
# 1. Setup venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 2. Configure
# Edit aumentum_browser_service.py with your settings

# 3. Start
./PLAGIS_AUMENTUM/START_API.sh

# 4. Test
curl http://localhost:8001/docs
```

## 🎯 API Usage Examples

### Resolve Content by Document Number
```bash
curl "http://localhost:8001/documents/by-document-number?document_number=BP3208"
```

Response:
```json
{
  "document_number": "BP3208",
  "count": 1,
  "items": [
    {
      "id": 67131,
      "uuid": "dcb3a0d9-2a29-4441-afaa-919d32f1826d",
      "content_url": "store://2014/12/18/16/20/e03a480a-f6ef-477f-b453-0d9d094dac16.bin",
      "content_size": 658455,
      "mimetype_str": "image/jpeg"
    }
  ]
}
```

### Stream PDF to Browser
```bash
# Open in browser
http://localhost:8001/documents/pdf-by-document-number?document_number=BP3208
```

### View API Documentation
```
http://localhost:8001/docs
```

## 🔍 Database Schema (LRS43)

### Key Tables
- `LRSAdmin.lr_parcel` - Parcel/Property records
- `LRSAdmin.lr_source_document` - Source documents
- `LRSAdmin.lr_admin_source_document` - Links parcels to documents
- `LRSAdmin.lr_transaction_document` - Links transactions to documents
- `LRSAdmin.alf_node` - Alfresco document nodes
- `LRSAdmin.alf_node_properties` - Document metadata (includes document_number)
- `LRSAdmin.alf_content_data` - File metadata
- `LRSAdmin.alf_content_url` - Storage paths (store:// URLs)

### Query Flow
```
LRSAdmin.lr_source_document.document_number = 'BP3208'
    ↓
alf_node_properties.string_value = 'BP3208' + qname.local_name IN ('targetRids','sourceRids')
    ↓
alf_node.id = alf_node_properties.node_id
    ↓
alf_content_data.id = alf_node.id
    ↓
alf_content_url.id = alf_content_data.content_url_id
    ↓
content_url = 'store://YYYY/M/D/H/M/UUID.bin'
```

## 🛠️ Configuration

### MSSQL Connection
```python
DEFAULT_DB_CONFIG = {
    "backend": "mssql",
    "server": "10.10.10.3",  # or HOST\\INSTANCE
    "port": 1433,
    "database": "LRS43",
    "username": "sa",
    "password": "YOUR_PASSWORD",
    "driver": "ODBC Driver 18 for SQL Server",
    "encrypt": "no",
    "trust_server_certificate": "yes",
}
```

### Contentstore Path
```python
DEFAULT_CONTENTSTORE_BASE = r"C:\Alfresco\alf_data\contentstore"
```

## 📊 System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Browser / Extension                      │
│  (Chrome/Edge extension or direct API calls)                │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTP/JSON
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                   FastAPI REST Server                        │
│                  (aumentum_api.py)                           │
│  - /documents/by-document-number                             │
│  - /documents/pdf-by-document-number                         │
│  - /lrs/source-documents                                     │
│  - /lrs/content/recent                                       │
│  - /documents/pdf-by-store-url                               │
└───────────────────────┬─────────────────────────────────────┘
                        │
            ┌───────────┴───────────┐
            │                       │
            ▼                       ▼
┌─────────────────────┐    ┌─────────────────────┐
│  Service Layer      │    │   File System       │
│ (aumentum_browser   │    │  (contentstore/)    │
│    _service.py)     │    │  Y/M/D/H/M/UUID.bin │
│                     │    └─────────────────────┘
│ - Database queries  │              │
│ - PDF conversion    │              │
│ - Path resolution   │              │
└──────────┬──────────┘              │
           │                         │
           ▼                         ▼
┌─────────────────────────────────────────────────────────────┐
│              Microsoft SQL Server 2012+                      │
│                   Database: LRS43                            │
│                                                               │
│  Schema: LRSAdmin                                            │
│  - alf_node, alf_content_data, alf_content_url              │
│  - lr_source_document, lr_parcel                            │
│  - lr_admin_source_document, lr_transaction_document        │
└─────────────────────────────────────────────────────────────┘
```

## 🔒 Security Considerations

- [ ] Add authentication middleware
- [ ] Configure HTTPS (production)
- [ ] Rate limiting on endpoints
- [ ] Input validation/sanitization
- [ ] SQL injection prevention (using parameterized queries)
- [ ] Path traversal prevention
- [ ] Firewall rules
- [ ] Service account with minimal permissions

## 🎉 Benefits

### For Users
- ✅ **No Silverlight required** - Modern browser compatibility
- ✅ **Fast document viewing** - Direct PDF streaming
- ✅ **Searchable** - Query by document number
- ✅ **Mobile-friendly** - Works on any device

### For Administrators
- ✅ **Easy deployment** - Single server setup
- ✅ **Maintainable** - Modern Python stack
- ✅ **Extensible** - REST API for integration
- ✅ **Replaceable** - Can migrate to newer servers

### For Developers
- ✅ **Documented** - Comprehensive docs
- ✅ **Tested** - Connection and endpoint tests
- ✅ **Modular** - Clean separation of concerns
- ✅ **Standard** - FastAPI best practices

## 🚦 Status

### ✅ Working Now
- Database queries (MSSQL ready, needs Windows server)
- Document resolution logic
- PDF conversion pipeline
- REST API structure
- Browser extension skeleton

### ⚠️ Needs Configuration
- MSSQL ODBC driver installation
- Database credentials
- Contentstore path mapping
- Network connectivity

### 🎯 Next Steps
1. Deploy to Windows Server with SQL Server
2. Test with real data
3. Add authentication
4. Configure HTTPS
5. Set up monitoring

## 📞 Support

For issues or questions:
1. Check troubleshooting sections in docs
2. Run `test_db_connection.py` for diagnostics
3. Check server logs
4. Verify ODBC driver installation

---

**Last Updated:** Based on Aumentum Registry LRS43 database schema  
**Version:** 1.0.0  
**Status:** Ready for Windows deployment