Architecture Principles

The architecture of Attendrix is built upon four foundational design principles. These principles inform database schema design, client-side caching strategies, and serverless background execution.

1. Single Relational Source of Truth

All persistent state (academic enrollments, class slot occurrences, logged absences, and device tokens) is mastered within PostgreSQL 17.

• No Split-Brain Persistence: We avoid dual-writing between mobile storage and external databases. Mobile local storage acts purely as a deterministic cache of the PostgreSQL master.
• Relational Integrity Over Client Logic: Foreign key constraints (ON DELETE CASCADE, ON DELETE RESTRICT), CHECK constraints, and database triggers enforce business invariants at the persistence layer, making it impossible for buggy client versions to corrupt institutional data.

2. Inverted Attendance Storage Model

Traditional attendance systems store positive records for every student present in every lecture, resulting in massive write amplification:

Daily Inserts = N_students * N_classes * 0.85

For 5,000 students taking 5 classes per day, this generates 21,250 rows daily.

• 80%+ Write Reduction: Because average attendance is 80–90%, logging only absences reduces database row creation by more than 80%.
• Zero-Row Initialization: When a student enrolls in a new course, their attendance is instantly 100% without inserting a single row.

3. 100% Offline Pedestrian Autonomy

Students frequently navigate campus with intermittent cellular connectivity or in basement lecture halls with zero signal.

• Precomputed All-Pairs Shortest Paths: The university pedestrian path network (comprising 152,904 coordinate pairs across buildings and intersections) is precomputed using pgRouting and published as a versioned binary/JSON dataset.
• In-Memory Graph Matrix: The mobile app downloads the dataset once upon initial onboarding. Destination lookups and ETA calculations perform simple memory lookups, ensuring 0ms latency and 100% offline availability.

4. Decoupled Asynchronous Processing via PGMQ

External API interactions (Google Calendar API rate limits, OneSignal push network timeouts) must never block client database transactions or mobile user interactions.

• Transactional Enqueueing: Database triggers push messages into PostgreSQL Message Queues (PGMQ) within the same ACID transaction as the triggering SQL statement.
• Statement Coalescing: When 50 classes are updated in a batch import, a single statement-level trigger generates one coalesced PGMQ job instead of 50 individual events.
• Idempotency & Visibility Timeouts: Edge Function workers process queue jobs with distributed leases and visibility timeouts (vt = 180s), ensuring resilience against transient network drops without duplicate execution.