Skip to content

Home

Jump to bottom
Shivang Sagar edited this page Sep 29, 2026 · 1 revision

Welcome to the Presencia wiki!

Presencia — Technical Documentation & Architecture Manual

Welcome to the comprehensive technical documentation for Presencia, an offline-first Android attendance management utility built with modern declarative UI standards.

1. Project Overview & Philosophy

Presencia addresses the core need for minimal, privacy-centric class attendance monitoring without intrusive server dependencies or cloud sync overhead.

Core Design Pillars:

  • Zero Overhead / Frictionless Interaction: One-tap attendance marking with instantaneous UI state updates.
  • Strict Privacy & Offline Integrity: No network permissions requested in the manifest; data persists strictly within application-sandboxed storage.
  • High Contrast Accessibility: True OLED black (#000000) and pure white (#FFFFFF) themes optimized for legibility under bright sunlight and minimal battery drainage.
  • Longitudinal Date Support: Deterministic, custom grid calendar architecture functioning seamlessly between January 2026 and December 2077.

2. Technical Stack & Build Configurations

Layer Technology Details / Rationale
Language Kotlin (JVM Target 11) Null safety, concise state mutability, coroutine readiness
UI Toolkit Jetpack Compose (Material 3) Declarative UI, state-driven reactivity, zero XML overhead
Architecture MVVM Pattern Clear separation of UI presentation from business storage
Serialization Google Gson Lightweight JSON serialization for sandboxed SharedPreferences
Persistence Android SharedPreferences Native key-value store, instant initialization, deterministic wiping on app uninstall
Build System Gradle Kotlin DSL (build.gradle.kts) Declarative build system targeting modern Android compilation

SDK Specifications:

  • Application ID / Package: com.shivangsagar.presencia
  • Minimum SDK: API Level 24 (Android 7.0 Nougat)
  • Target / Compile SDK: API Level 37 (Android 16+)
  • Dependencies:
    • androidx.compose.material3:material3
    • androidx.compose.material:material-icons-extended
    • androidx.lifecycle:lifecycle-viewmodel-compose:2.8.6
    • com.google.code.gson:gson:2.10.1

3. Architecture & Data Flow

Presencia follows a lightweight Model-View-ViewModel (MVVM) pattern:

┌────────────────────────────────────────────────────────┐
│                      UI Layer                          │
│  (MainActivity -> AppNavigation -> Screen Composables) │
└───────────────────────────▲────────────────────────────┘
                            │ State Observation
                            ▼
┌────────────────────────────────────────────────────────┐
│                   PresenciaViewModel                   │
│   (State management, mutability triggers, validation)  │
└───────────────────────────▲────────────────────────────┘
                            │ Serialization / Persistence
                            ▼
┌────────────────────────────────────────────────────────┐
│                     StorageManager                     │
│           (Gson String Engine <-> SharedPreferences)   │
└────────────────────────────────────────────────────────┘

Data Structures:

  • SubjectData:
    • id: String (UUID v4 — guarantees unique item identification across deletions)
    • name: String (Subject title string)
    • attendanceData: MutableMap<String, Boolean> (Date strings in ISO-8601 YYYY-MM-DD mapping to attendance status: true for Present, false for Absent)

4. Component Breakdown & Lifecycle

StorageManager

Handles the encoding and extraction of serialized application entities:

  • saveSubjects(List<SubjectData>): Serializes subjects list to JSON format using reflection via TypeToken.
  • getSubjects(): Deserializes the existing records, falling back to an empty list on first application startup.
  • saveTheme(Boolean) / getTheme(): Retains user preference for Dark/Light mode between application lifecycles.

PresenciaViewModel

Encapsulates runtime data and executes business rules:

  • Subject Creation Validation: Guarded by isNotBlank() logic to suppress empty dialog submissions.
  • Granular Attendance Tracking: Modifies specific date keys in attendanceData without altering previous records.
  • Attendance Removal (removeAttendance): Strips marked records from the map to restore neutral calendar status.
  • Lifecycle Reinitialization: Keyed Compose states (key(subject.id)) ensure edit dialog fields dynamically bind to the correct subject title, eliminating index-offset visual bugs during batch operations.

5. UI Features & Screen Breakdown

Home Screen (HomeScreen & SubjectItem)

  1. Dynamic Donut Gauge:
    • Utilizes Compose Canvas drawing arcs with smooth StrokeCap.Round.
    • Outer track uses adaptive contrast (Color(0xFFE0E0E0) in light theme, Color.DarkGray in dark theme).
    • Foreground arc sweep maps dynamically via: Sweep Angle = (Present / Total) * 360
  2. Contextual Action Menus:
    • Inline Edit dialog with persistent text fields.
    • Single-item removal triggering instant list re-indexing.
  3. Global Control TopBar:
    • Theme switcher updating system status bar icons and full palette.
    • Multi-select toggle transitioning the primary '+' trigger into a bulk-delete confirmation modal.

Calendar Detail Screen (CalendarScreen)

  1. System Back Navigation Handling: Integrated BackHandler routes hardware back actions to return to HomeScreen rather than terminating the application task.
  2. Custom Calendar Engine:
    • Computes starting day offsets dynamically using java.time.LocalDate.dayOfWeek.
    • Standard 7-column layout mapping days accurately without heavy third-party calendar libraries.
    • Current date emphasized via FontWeight.Bold and high-contrast double borders.
  3. Four Statistical Metric Nodes:
    • Present Count: Total instances where value evaluates to true.
    • Absent Count: Total instances where value evaluates to false.
    • Total Classes: Dynamic calculation (Present + Absent).
    • Percentage Calculation: Displayed as an integer ceiling/floor percentage (0% fallback for empty states).
  4. Subject Hard Reset: Accessible at the bottom; purges map data for the active subject ID after dual-confirmation dialogue validation.

6. Local Setup, Build & Deployment Guide

Prerequisites

  • Android Studio Ladybug | Jellyfish | Meerkat or newer
  • JDK 11 installed and configured in project structure
  • Android device or emulator running API 24+

Step-by-Step Compilation:

  1. Clone the repository: 
    git clone [https://github.com/TUMHARA_USERNAME/Presencia.git](https://github.com/TUMHARA_USERNAME/Presencia.git)
  2. Open Android Studio and select Open, browsing to the project root directory.
  3. Allow Gradle to execute build script evaluation and download dependencies.
  4. Build signed APK or run directly via terminal: 
    ./gradlew assembleRelease
    The compiled APK binary will be produced under: 
    app/build/outputs/apk/release/

7. Security, Integrity & Data Persistence

  • Sandboxing: Data saved via Context.MODE_PRIVATE is isolated from external app inspection on non-rooted devices.
  • Clean State Guarantee: Application uninstall completely flushes cache and shared preferences via native Android package manager protocols.
  • No Telemetry: Zero analytics trackers, background daemons, or internet sockets initialized.

Clone this wiki locally