Platform Architecture

TitanGrid acts as an enterprise middleware layer. By providing stateless, unified data ingestion routes, the platform harmonizes telemetry streams from multiple hardware providers concurrently, processing them into clean, audit-ready data ledgers.

1. Infrastructure & Server Topology

The production backend operates within an isolated cloud environment utilizing an Ubuntu Linux instance. The server stack is optimized for high-concurrency ingestion, ensuring that external biometric clock pushes do not block client API requests.

• Nginx Reverse Proxy: Acts as the outer defensive boundary, handling static file routing and routing incoming port 80 (ZKTeco) and port 443 (Suprema Webhooks) traffic.
• Gunicorn WSGI: The application server daemonizes the Python processes, maintaining a worker pool capable of handling simultaneous inbound hardware events.
• Django / DRF Application: The core brain of the system, responsible for executing complex roster cycle parsing, midnight crossings tracking, and HTTP payload decoding.

2. Authentication & Authorization Matrix

The system implements a rigid four-tier access control structure designed to isolate tenant data and enforce operational boundaries across the enterprise.

Access Control Levels

1. Superusers: Global system owners with unrestrained access to system configurations, database parameters, and all organizational units.
2. Administrators: High-level operational managers capable of managing platform settings and overseeing multiple departments.
3. Human Resources (HR): Focused specifically on analytics, payroll exports, and managing the AttendanceRecord tables without possessing deep system configuration rights.
4. Department Managers: Siloed users restricted to viewing and managing only the personnel assigned to their specific local department grid.

Registration & Role Assignment Logic

During user provisioning, role assignments are tightly controlled to prevent escalation of privilege. The system utilizes specific management dropdown constraints:

Important Constraint: Only Superusers and Administrators possess the authority to select the "Administrator" and "Human Resource" roles directly from the department selection dropdown during the registration of new high-level personnel.

3. Database Schema & Data Strategy

The core data management tier guarantees strict boundary isolation and atomic calculations over heavy temporal data entries.

The Two-Stage Ingestion Pipeline

To prevent vendor lock-in and ensure data integrity, the system splits incoming biometric punches into two distinct database models:

A. The Immutable Ledger (AttendanceLog)

This acts as a "sink." Every biometric check caught by the edge endpoints is committed here instantly. It stores the raw timestamp, verification method, and hardware device properties. This table is strictly append-only and is never retroactively modified.

B. The Aggregated Matrix (AttendanceRecord)

A background processor parses the AttendanceLog against the employee's assigned shift policies. The calculated results—including dynamically computed integer fields for minutes worked, late calculations, and overtime durations—are stored here to feed the Next.js frontend reporting interface.

4. Hardware Ingestion Interfaces

The platform interfaces directly with leading biometric device protocols at the network edge.

Example: DRF Ingestion Endpoint Snippet

When a Hikvision or Suprema terminal pushes a payload, the Django REST Framework intercepts and decodes the stream before committing it to the Ledger.

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from .models import AttendanceLog
 
class HardwareIngestionGateway(APIView):
    """
    Stateless endpoint for receiving normalized JSON payloads 
    from biometric hardware terminals.
    """
    def post(self, request):
        terminal_sn = request.data.get('serial_number')
        emp_code = request.data.get('employee_no')
        punch_time = request.data.get('timestamp')
        
        # 1. Commit to Immutable Ledger
        log_entry = AttendanceLog.objects.create(
            terminal_sn=terminal_sn,
            employee_code=emp_code,
            punch_time=punch_time,
            is_processed=False
        )
        
        return Response(
            {"status": "success", "ledger_id": log_entry.id}, 
            status=status.HTTP_201_CREATED
        )