PHPackages                             mavis-creator/blockchain-attendance-system - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. mavis-creator/blockchain-attendance-system

ActiveProject[Security](/categories/security)

mavis-creator/blockchain-attendance-system
==========================================

A secure, blockchain-verified attendance management system with device fingerprinting, IP tracking, and log-based storage (no SQL required)

v2.0.0(7mo ago)10[1 issues](https://github.com/MAVIS-creator/Blockchain-Based-Attendance-System/issues)MITPHPPHP &gt;=7.4CI passing

Since Nov 26Pushed 2mo agoCompare

[ Source](https://github.com/MAVIS-creator/Blockchain-Based-Attendance-System)[ Packagist](https://packagist.org/packages/mavis-creator/blockchain-attendance-system)[ Docs](https://github.com/MAVIS-creator/Blockchain-Based-Attendance-System)[ RSS](/packages/mavis-creator-blockchain-attendance-system/feed)WikiDiscussions main Synced 2mo ago

READMEChangelogDependencies (4)Versions (3)Used By (0)

 [![Blockchain-Secured Attendance System](asset/banner.png)](asset/banner.png)

🛡️ Blockchain-Secured Attendance System
=======================================

[](#️-blockchain-secured-attendance-system)

 **A tamper-proof, AI-powered, SQL-free attendance management platform — secured by blockchain-style log chaining, device fingerprinting, geofencing, and real-time revocation.**

 [![PHP 8.2](https://camo.githubusercontent.com/3214f964789e57e383f3840659005a9ebd6460d46ad610071b99dbb44cbadbde/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322d3737374242343f7374796c653d666f722d7468652d6261646765266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/3214f964789e57e383f3840659005a9ebd6460d46ad610071b99dbb44cbadbde/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322d3737374242343f7374796c653d666f722d7468652d6261646765266c6f676f3d706870266c6f676f436f6c6f723d7768697465) [![Storage](https://camo.githubusercontent.com/270a466701607201bc595141698e53362ca3eca1b920e3041ed43031a963c69e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53746f726167652d4c6f672532302532422532304a534f4e2d3265636337313f7374796c653d666f722d7468652d6261646765266c6f676f3d66696c6573266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/270a466701607201bc595141698e53362ca3eca1b920e3041ed43031a963c69e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53746f726167652d4c6f672532302532422532304a534f4e2d3265636337313f7374796c653d666f722d7468652d6261646765266c6f676f3d66696c6573266c6f676f436f6c6f723d7768697465) [![Blockchain](https://camo.githubusercontent.com/e60e71dc577468a144ab4a78df6085d4386c96fa89532d16d92d0b6007b4351f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f426c6f636b636861696e2d5348412d2d323536253230436861696e696e672d4637393331413f7374796c653d666f722d7468652d6261646765266c6f676f3d626974636f696e266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/e60e71dc577468a144ab4a78df6085d4386c96fa89532d16d92d0b6007b4351f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f426c6f636b636861696e2d5348412d2d323536253230436861696e696e672d4637393331413f7374796c653d666f722d7468652d6261646765266c6f676f3d626974636f696e266c6f676f436f6c6f723d7768697465) [![AI](https://camo.githubusercontent.com/0c311b684872521126cf1aed551fb953fe17b03e427ed9e9def18c1979779c34/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f41492d506f77657265642d3842354346363f7374796c653d666f722d7468652d6261646765266c6f676f3d6f70656e6169266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/0c311b684872521126cf1aed551fb953fe17b03e427ed9e9def18c1979779c34/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f41492d506f77657265642d3842354346363f7374796c653d666f722d7468652d6261646765266c6f676f3d6f70656e6169266c6f676f436f6c6f723d7768697465) [![Azure](https://camo.githubusercontent.com/12df4ef19df7bb8467ab3546883de41ce335a502eea9a0f3548893a5398565fd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f417a7572652d4465706c6f7965642d3030373844343f7374796c653d666f722d7468652d6261646765266c6f676f3d6d6963726f736f6674617a757265266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/12df4ef19df7bb8467ab3546883de41ce335a502eea9a0f3548893a5398565fd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f417a7572652d4465706c6f7965642d3030373844343f7374796c653d666f722d7468652d6261646765266c6f676f3d6d6963726f736f6674617a757265266c6f676f436f6c6f723d7768697465) [![MIT License](https://camo.githubusercontent.com/f77c46cfd34df0f2783a9d96cc43ac41093d5ede3f6ff47dac0b1cfc7bf3a2c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d3232633535653f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/f77c46cfd34df0f2783a9d96cc43ac41093d5ede3f6ff47dac0b1cfc7bf3a2c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d3232633535653f7374796c653d666f722d7468652d6261646765)

 [**🌐 Live Site**](https://smart-attendance-samex.me) · [**⚡ Quickstart**](QUICKSTART.md) · [**📋 Full Feature Inventory**](FEATURES_IMPLEMENTED.md) · [**🤝 Contribute**](CONTRIBUTING.md)

---

📖 What Is This?
---------------

[](#-what-is-this)

A **production-grade attendance system** that replaces traditional SQL databases with an append-only, blockchain-chained log architecture. Every attendance record is cryptographically linked to the one before it using **SHA-256 hashing** — making silent data tampering detectable at a glance.

On top of that foundation, the system layers:

- 🤖 **AI-powered** ticket automation, announcements, admin chat, and rulebook enforcement
- 🔐 **Enterprise security** — geofencing, IP whitelisting, device fingerprinting, CSRF, AES-256 encryption
- 📧 **Automated email reporting** — CSV/PDF exports on schedule
- 🔗 **Optional Polygon/Web3** anchoring for decentralised hash storage
- ☁️ **Azure App Service** ready, with Supabase hybrid dual-write support

> **No SQL. No database server. No single point of failure.** All records live in structured log files and JSON stores — blazing fast and portable.

---

✨ Feature Highlights
--------------------

[](#-feature-highlights)

### 👤 Student / User Side

[](#-student--user-side)

FeatureDescription**Check-In / Check-Out**Attendance submission with full validation — mode gating, duplicate detection, cooldowns**Device Fingerprinting**Ties submissions to a specific device; mismatches are blocked and logged**Support Tickets**Students submit issues with auto-captured IP and fingerprint for context**Live Announcements**JSON-powered announcements displayed instantly on the landing page**Closed-State Pages**Graceful UI when attendance windows are inactive or the system is closed**Blockchain Receipt**Every valid submission appends a cryptographically signed block to the chain---

### 🛠️ Admin Panel

[](#️-admin-panel)

#### 🎛️ Attendance Control

[](#️-attendance-control)

- Toggle **check-in / check-out** modes with optional duration timers and end-time countdowns
- **Manual attendance** entry with reason validation and full enforcement rule reuse
- **Active course** management — bind or unbind which course is accepting attendance

#### 📊 Logs &amp; Monitoring

[](#-logs--monitoring)

- **Valid attendance log viewer** with date, course, and column filters + pagination
- **Failed attempts viewer** — every rejected submission is logged with a reason code
- **Audit log** with retention-based purge controls for sensitive admin actions
- **Request timing tracker** (`request_timings.php`) for performance visibility
- **Inactivity logger** with blocked-token rotation (`log_inactivity.php`)
- **Real-time dashboard refresh** via file-change polling (`_last_updates.php`)

#### 📤 Export &amp; Email

[](#-export--email)

- Multi-file log selection grouped by **date + course**
- Filter by **date range**, **time range**, and **course**
- Select specific **columns** to include in the export
- Export as **CSV** or **PDF** (DomPDF)
- Send via **SMTP / PHPMailer** — individually or in grouped batches
- **Scheduled auto-send** via `auto_send_logs.php` (cron/task-scheduler compatible)

#### 🔗 Blockchain &amp; Integrity

[](#-blockchain--integrity)

- Every valid submission writes a **SHA-256 block** linked to the previous block's hash
- Admin **chain validator** (`chain.php`) shows full chain with tamper indicators
- **Chain repair utility** (`fix_chain.php`) recomputes hashes after authorised corrections
- Optional **Polygon / Web3** anchoring — push chain hashes to the blockchain network

#### 🔒 Security &amp; Revocation

[](#-security--revocation)

- **IP whitelist** with CIDR range support
- **Geofence enforcement** using real-time Haversine distance calculations
- **User-agent lock** — binds a device fingerprint to a specific browser UA
- **Cooldown enforcement** — prevents rapid sequential submissions
- **AES-256-CBC** encryption for settings and sensitive log stores
- **CSRF tokens** on all admin write operations
- **Token / IP / MAC revocation** with expiry metadata
- **Real-time revocation SSE** (`revoke_sse.php`) — clients get kicked instantly
- **Fingerprint unlinking** from matric records

#### 🤖 AI Features

[](#-ai-features)

- **AI Ticket Automation Engine** — classifies, diagnoses, and suggests resolutions for support tickets
- **AI Announcement Service** — generates contextual announcements using AI providers
- **AI Suggestion Engine** — admin-facing AI that surfaces actionable insights
- **AI Rulebook** — configurable policy engine with provider-backed enforcement
- **AI Admin Chat Assistant** — admin chat with AI integration
- **AI Context Preview** — live preview of the AI's site structure understanding

#### 👥 Accounts &amp; Roles

[](#-accounts--roles)

- Multi-admin support with **role-aware sessions** (admin vs. superadmin)
- Superadmin-gated account creation and deletion
- Self-service password changes and supervisor-initiated resets
- Forgot password flow with secure token delivery

#### 📦 Backup &amp; Restore

[](#-backup--restore)

- **ZIP backup** of logs, fingerprints, and blockchain chain data
- **Restore from ZIP upload** — fully reconstructs state from a backup
- Clear operations UI (logs / backups / chain / tokens) with confirmation guards

#### 💬 Communication

[](#-communication)

- **Admin-to-admin internal chat** with role controls and delete support
- **Announcement system** — create, edit, enable/disable with instant propagation
- **Support ticket viewer** with manual attendance action directly from ticket context

---

🔐 Security Architecture
-----------------------

[](#-security-architecture)

```
Submission Request
       │
       ▼
 ┌─────────────────────────────────────────────────────┐
 │  1. Input sanitization (filter_var + trim)          │
 │  2. Mode gate check (checkin/checkout enabled?)     │
 │  3. IP whitelist / CIDR validation                  │
 │  4. Geofence Haversine distance check               │
 │  5. Device fingerprint lookup & mismatch detection  │
 │  6. User-agent lock enforcement                     │
 │  7. Cooldown window enforcement                     │
 │  8. Duplicate detection (matric + device + day)     │
 │  9. Checkout-without-checkin guard                  │
 │ 10. CSRF token validation (admin paths)             │
 └─────────────────────────────────────────────────────┘
       │  All checks passed
       ▼
 ┌─────────────────────────────────────────────────────┐
 │  Write to pipe-delimited .log file (flock LOCK_EX)  │
 │  Append SHA-256 block to attendance_chain.json      │
 │  Optional: anchor hash to Polygon network           │
 └─────────────────────────────────────────────────────┘

```

---

🏗️ Tech Stack
-------------

[](#️-tech-stack)

LayerTechnology**Language**PHP 8.2**Storage**Flat-file `.log` + JSON (no SQL)**Blockchain**Custom SHA-256 hash chaining**Web3**`web3p/web3.php` → Polygon RPC**Email**PHPMailer (SMTP)**PDF Export**DomPDF**AI Providers**Configurable (OpenAI-compatible endpoints)**Auth**Custom session management (`ATTENDANCE_ADMIN_SESSION`)**Hosting**Azure App Service (Linux / PHP 8.2)**Optional Cloud DB**Supabase (hybrid dual-write mode)**CI/CD**Git push-to-deploy via Azure Kudu / Oryx---

📦 Installation
--------------

[](#-installation)

### Option A — Git Clone (Recommended)

[](#option-a--git-clone-recommended)

```
git clone https://github.com/MAVIS-creator/Blockchain-Based-Attendance-System.git
cd Blockchain-Based-Attendance-System
composer install
cp .env.example .env
# Edit .env with your settings
php -S localhost:8000
```

### Option B — Composer Create-Project

[](#option-b--composer-create-project)

```
composer create-project mavis-creator/blockchain-attendance-system attendance-system
cd attendance-system
cp .env.example .env
php -S localhost:8000
```

### Option C — XAMPP / WAMP (Local)

[](#option-c--xampp--wamp-local)

1. Install [XAMPP](https://www.apachefriends.org/) or [WAMP](https://www.wampserver.com/)
2. Place the project folder inside `htdocs/` (XAMPP) or `www/` (WAMP)
3. Start Apache
4. Visit `http://localhost/Blockchain-Based-Attendance-System/`

> 📖 **Detailed setup:** see [INSTALL.md](INSTALL.md) and [QUICKSTART.md](QUICKSTART.md)

---

⚙️ Configuration (`.env`)
-------------------------

[](#️-configuration-env)

```
# ── Application ─────────────────────────────────────
APP_ENV=production
APP_DEBUG=false
APP_TIMEZONE=Africa/Lagos

# ── Session ──────────────────────────────────────────
SESSION_LIFETIME=120
SESSION_SAVE_PATH=           # leave blank for auto-detection

# ── SMTP Email ───────────────────────────────────────
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_SECURE=tls
FROM_EMAIL=no-reply@example.com
FROM_NAME=Attendance System

# ── Security ─────────────────────────────────────────
FINGERPRINT_ENABLED=true
MAX_CHECKINS_PER_DAY=1
ENCRYPT_LOGS=false

# ── Blockchain / Web3 (optional) ─────────────────────
POLYGON_RPC_URL=
POLYGON_PRIVATE_KEY=
POLYGON_CHAIN_ID=137

# ── Supabase Hybrid (optional) ───────────────────────
SUPABASE_URL=
SUPABASE_KEY=
```

See [.env.example](.env.example) for the full annotated reference.

### ☁️ Hybrid Supabase Mode (Optional)

[](#️-hybrid-supabase-mode-optional)

Enable cloud-backed dual-write while keeping local file reliability:

1. Run [`supabase/schema.sql`](supabase/schema.sql) in your Supabase project
2. Follow [`supabase/HYBRID_SETUP.md`](supabase/HYBRID_SETUP.md) for rollout steps

---

🗂️ Project Structure (Condensed)
--------------------------------

[](#️-project-structure-condensed)

```
📁 Blockchain-Based-Attendance-System/
├── index.php                  # Student attendance landing page
├── submit.php                 # Attendance submission + all validation + chain write
├── support.php                # Student support ticket form
├── closed.php                 # Closed-state page (rich UI)
├── polygon_hash.php           # Polygon/Web3 hash anchoring
├── storage_helpers.php        # Unified storage path resolution
├── bootstrap.php              # App bootstrap (env, timezone, autoload)
│
├── 📁 admin/
│   ├── dashboard.php          # Main admin shell
│   ├── status.php             # Enable/disable check-in & check-out modes
│   ├── settings.php           # All configurable parameters (77KB!)
│   ├── accounts.php           # Multi-admin account management
│   ├── chain.php              # Blockchain chain validator UI
│   ├── send_logs_email.php    # Export + email logs (CSV/PDF)
│   ├── manual_attendance.php  # Manual attendance entry
│   ├── view_tickets.php       # Support ticket viewer + resolution
│   ├── announcement.php       # Announcement CRUD
│   ├── geofence.php           # Geofence configuration UI
│   ├── audit.php              # Audit log viewer + purge
│   ├── patcher.php            # In-app live patcher (128KB engine)
│   ├── roles.php              # Role permission management
│   ├── profile_settings.php   # Admin profile + password management
│   ├── session_bootstrap.php  # Unified session initializer
│   └── 📁 includes/
│       ├── header.php         # Shared admin page header
│       ├── navbar.php         # Admin navigation bar
│       └── csrf.php           # CSRF token helpers
│
├── 📁 src/
│   ├── AiProviderClient.php         # AI provider abstraction (39KB)
│   ├── AiRulebook.php               # AI policy rulebook engine (32KB)
│   ├── AiTicketAutomationEngine.php # AI ticket processing (31KB)
│   ├── AiTicketDiagnoser.php        # AI ticket diagnostics (18KB)
│   ├── AiSuggestionService.php      # AI admin suggestions (13KB)
│   ├── AiSiteStructureContext.php   # AI site context builder (13KB)
│   ├── AiAnnouncementService.php    # AI announcement generation (8KB)
│   └── Config.php                   # PSR-4 config loader
│
└── 📁 supabase/               # Optional hybrid cloud schema & docs

```

---

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! We have a structured workflow:

- 🐛 **Bug reports** — use the structured issue form in GitHub Issues
- 💡 **Feature requests** — open a feature/improvement issue
- 🔀 **Pull Requests** — follow the PR template in `.github/`
- 📖 Full details in [CONTRIBUTING.md](CONTRIBUTING.md)

---

📄 Changelog
-----------

[](#-changelog)

See [CHANGELOG.md](CHANGELOG.md) for a full history of releases and changes.

---

🔏 Security Policy
-----------------

[](#-security-policy)

For responsible disclosure of vulnerabilities, see [SECURITY.md](SECURITY.md).

---

📜 License
---------

[](#-license)

This project is licensed under the **MIT License** — see [LICENSE](LICENSE) for details.

---

 **Built with ❤️ by**

 [**Mavis**](https://github.com/MAVIS-creator) — Gamer · Web Developer · Security Enthusiast
 📧

 **Co-Authors &amp; Collaborators**

 [**SamexHighshow**](https://github.com/SamexHighshow) · Co-Author
 [**Bakare Olamilekan Abdulkarim**](https://github.com/bakareolamilekan365-tech) · Collaborator

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance58

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 99.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

219d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/174819191?v=4)[Akintunde Dolapo Elisha](/maintainers/MAVIS-creator)[@MAVIS-creator](https://github.com/MAVIS-creator)

---

Top Contributors

[![MAVIS-creator](https://avatars.githubusercontent.com/u/174819191?v=4)](https://github.com/MAVIS-creator "MAVIS-creator (393 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (3 commits)")

---

Tags

attendance-systemblockchaincollaboratecssmicrosoftnamecheapphpprivate-blockchainprivate-repositoryphpsecurityPolygonweb3blockchainfingerprintingattendanceattendance-systemlog-based

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mavis-creator-blockchain-attendance-system/health.svg)

```
[![Health](https://phpackages.com/badges/mavis-creator-blockchain-attendance-system/health.svg)](https://phpackages.com/packages/mavis-creator-blockchain-attendance-system)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)[helsingborg-stad/municipio

A bootstrap theme for creating municipality sites.

4028.5k10](/packages/helsingborg-stad-municipio)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
