# Workstation System Documentation

## Overview

The Aumentum Registry System now includes a comprehensive workstation-based architecture that provides role-specific interfaces for different user types. This system is based on the Aumentum Registry architecture and provides specialized workstations for various operational needs.

## Workstations

### 1. Web Access (General)
- **Route**: `/dashboard`
- **Access**: All authenticated users
- **Features**:
  - Property Search
  - Document Search
  - Transaction Search
  - Party Search
  - Boundary Search

### 2. Administrator Workstation
- **Route**: `/workstation/administrator`
- **Access**: Users with `ROLE_ADMINISTRATOR`
- **Features**:
  - User Management
  - Role Management
  - System Configuration
  - Database Administration
  - Audit Logs
  - Report Generation

### 3. Cashier Workstation
- **Route**: `/workstation/cashier`
- **Access**: Users with `ROLE_CASHIER` or `ROLE_ADMINISTRATOR`
- **Features**:
  - Fee Collection
  - Payment Processing
  - Receipt Generation
  - Transaction Fees
  - Payment History
  - Financial Reports

### 4. GIS Viewer
- **Route**: `/workstation/gis-viewer`
- **Access**: All authenticated users
- **Features**:
  - Interactive Maps
  - Property Boundaries
  - Spatial Queries
  - Layer Management
  - Measurement Tools
  - Print Maps
  - QGIS Integration

### 5. Indexing Workstation
- **Route**: `/workstation/indexing`
- **Access**: All authenticated users
- **Features**:
  - Property Indexing
  - Document Indexing
  - Batch Indexing
  - Quality Control
  - Index Reports
  - Data Validation

### 6. Archiving System
- **Route**: `/workstation/archiving`
- **Access**: All authenticated users
- **Features**:
  - Document Upload
  - Archive Management
  - Document Retrieval
  - Version Control
  - Bulk Operations
  - Archive Reports

## API Endpoints

### GIS Endpoints

#### `GET /gis/properties/geojson`
Returns properties as GeoJSON for GIS viewers.

**Query Parameters**:
- `bbox` (optional): Bounding box (minx,miny,maxx,maxy)
- `property_number` (optional): Filter by property number

**Response**: GeoJSON FeatureCollection

#### `GET /gis/boundaries/geojson`
Returns boundary records as GeoJSON.

#### `GET /gis/qgis/connect`
QGIS extension connection endpoint. Returns connection info and available layers.

### Cashier Endpoints

#### `POST /cashier/payment`
Process a payment transaction.

**Request Body**:
```json
{
  "transaction_number": "TXN-20241205-001",
  "property_number": "PL-20241205-123456-7890",
  "amount": 50000.00,
  "payment_method": "cash",
  "description": "Property registration fee",
  "service_type": "registration"
}
```

**Response**:
```json
{
  "success": true,
  "payment_id": "PAY-20241205-123456-7890",
  "receipt_number": "RCP-20241205-12345",
  "message": "Payment of ₦50,000.00 processed successfully"
}
```

#### `GET /cashier/fees`
Get fee schedule for various services.

**Query Parameters**:
- `service_type` (optional): Filter by service type

#### `GET /cashier/payments`
Get payment history with optional filters.

**Query Parameters**:
- `start_date` (optional): Start date filter
- `end_date` (optional): End date filter
- `transaction_number` (optional): Filter by transaction number

## Workstation Selection

Users can access workstations through:

1. **Main Dashboard**: Click on "Workstations" card in the App Launcher
2. **Sidebar Navigation**: Click on "Workstations" in the sidebar
3. **Direct URL**: Navigate to `/workstation` to see available workstations

The system automatically filters available workstations based on user roles.

## Role-Based Access Control

Workstations use role-based access control:

- **No required roles**: Available to all authenticated users
- **Required roles**: Only users with matching roles can access

Roles are checked from the JWT token and user profile.

## Integration with Existing Systems

### Web Access
The existing web access system (`/dashboard`) remains available and is now part of the workstation system.

### Archiving System
The archiving system integrates with the existing document upload and retrieval functionality.

### Property Indexing
The property indexing workstation uses the existing `/property/index` endpoint and adds quality control and reporting features.

## QGIS Extension

The system provides API endpoints for QGIS integration:

1. **Connection**: `GET /gis/qgis/connect` - Establishes connection
2. **Data Layers**: 
   - Properties: `GET /gis/properties/geojson`
   - Boundaries: `GET /gis/boundaries/geojson`
3. **Authentication**: Uses JWT tokens for secure access

## Future Enhancements

1. **Spatial Database Integration**: Full geometry support for actual spatial queries
2. **Payment Gateway Integration**: Connect to payment processors
3. **Advanced GIS Features**: Measurement tools, spatial analysis
4. **Batch Operations**: Enhanced batch processing for indexing
5. **Audit Logging**: Comprehensive audit trail for all operations
6. **Reporting**: Advanced reporting and analytics

## File Structure

```
plagis-nextjs/src/
├── app/
│   └── workstation/
│       ├── page.tsx                    # Workstation selector
│       ├── workstation.css            # Selector styles
│       ├── administrator/
│       │   └── page.tsx               # Admin workstation
│       ├── cashier/
│       │   └── page.tsx               # Cashier workstation
│       ├── gis-viewer/
│       │   ├── page.tsx               # GIS viewer
│       │   └── gis-viewer.css         # GIS styles
│       ├── indexing/
│       │   └── page.tsx               # Indexing workstation
│       ├── archiving/
│       │   └── page.tsx               # Archiving workstation
│       └── workstation-detail.css     # Shared workstation styles
└── lib/
    └── workstation.ts                 # Workstation configuration and utilities
```

## Usage Examples

### Accessing Workstations

```typescript
import { getAvailableWorkstations, hasWorkstationAccess } from '@/lib/workstation';

// Get available workstations for user
const userRoles = ['ROLE_ADMINISTRATOR', 'ROLE_CASHIER'];
const available = getAvailableWorkstations(userRoles);

// Check access
const hasAccess = hasWorkstationAccess('administrator', userRoles);
```

### Processing Payment

```typescript
const response = await apiClient.post('/cashier/payment', {
  transaction_number: 'TXN-001',
  amount: 50000,
  payment_method: 'cash',
  service_type: 'registration'
});
```

### Fetching GIS Data

```typescript
const geojson = await apiClient.get('/gis/properties/geojson', {
  params: { property_number: 'PL-20241205-123456-7890' }
});
```

## Notes

- All workstations require authentication (JWT token)
- Role-based access is enforced at both frontend and backend
- GIS endpoints return GeoJSON format for compatibility with mapping libraries
- Payment processing currently uses mock responses (database integration pending)
- Spatial queries are simplified (full geometry support requires spatial database columns)