TLPH — DENR E-Services Portal

A multi-tier government e-services web portal for the Department of Environment and Natural Resources (DENR) of the Philippines. Citizens can apply for environmental permits and licenses online, while DENR staff at the municipal, regional, national, and super-admin levels process, approve, and track those applications through a structured workflow.

TLPH is a full-stack Flask web application backed by Google Cloud Firestore as the primary database and Firebase Authentication for identity management. It covers the complete lifecycle of DENR permit applications — from citizen submission and fee payment all the way through multi-level government review and final approval — while also providing integrated modules for Human Resource Management (HRM), Municipal Accounting, Inventory, System Logs, and a DENR-branded document print/PDF system.

Role-based access control is enforced server-side on every route via the @role_required(...) decorator in firebase_auth_middleware.py. Unauthenticated requests redirect to login; wrong-role requests redirect to the user's own dashboard.

• Firebase Authentication (via Pyrebase4) for login; server Flask session set via /api/set-session
• Email OTP verification on registration — 6-digit code with 10-minute expiry
• Role-based access control enforced on every route with @role_required
• Disabled account detection before rendering any page
• Cache-control headers (no-store) on all protected pages to prevent back-button access
• Environment variable isolation for all secrets (.env + firebase-credentials.json)

Applications follow a staged approval pipeline across all government levels:

User submits (pending)
    └─► Municipal Admin reviews → "to review"
            └─► Regional Admin approves → "approved" (regional)
                    └─► National Admin gives final approval → "nationalStatus: approved"

• Farm Visit Services: Initial visit, compliance, disease, soil, general visit
• Fertilizer Services: Input usage, chemical registration, emergency pest control, fertilizer/pesticide recommendations
• Financial Services: Subsidy, grant, loan, crop insurance, startup support
• Compensation: Typhoon disaster / pest damage compensation requests
• Seminars & Training: GAP training, pest/disease management, safe pesticide handling, nursery/propagation, regulatory compliance orientation

• Creates Xendit invoices for permit and license application fees
• Webhook receiver automatically updates Firestore transaction status on payment confirmation
• PDF receipt generation via ReportLab (downloadable)
• Transaction history visible at every role level (scoped to municipality / region / national)
• Payment statistics (total deposits, paid / pending / failed) on all dashboards

Available at municipal level and above:

• Company, Department & Designation management
• Employee records (hire date, designation, department, contact info)
• Attendance tracking and office shift scheduling
• Leave request management (file, approve, reject)
• Payroll computation and payslip generation
• Holiday calendar management

• Chart of Accounts (COA) templates and individual account entries per municipality
• Entities (offices, banks, organizational units)
• Deposit categories — linked to COA codes and revenue types
• Expense categories — organized by office and fund type
• Accounting dashboard with financial summary statistics
• Payment deposit recording and reconciliation

• Stock tracking per municipality/region/national level
• Stock history and movement reporting
• User-facing stock list view

• Official DENR-branded print styling (denr-print.css) with DENR green header
• Government document formatting with signature sections, security watermarks, and barcode-style reference numbers
• ReportLab-based PDF export for receipts and official documents
• Print preview page (denr-print-preview.html)

• Comprehensive action logging: login events, CRUD operations, account creation/disablement
• Logs stored in system_logs (municipal-scoped) and regional_system_logs (region-scoped) Firestore collections
• Device type detection (mobile / tablet / desktop) from User-Agent
• 180-day TTL retention with automatic cleanup
• Accessible at municipal, regional, and super-admin levels with appropriate scope filtering

• Complete models/ph_locations.py mapping all Philippine provinces to their municipalities
• Used in dropdowns throughout the system for location-based filtering and scoping

TLPH/
├── app.py                          # Main Flask application entry point
├── config.py                       # App configuration (session, mail, Firebase)
├── firebase_config.py              # Firebase Admin + Pyrebase initialization
├── firebase_auth_middleware.py     # Role-based access control decorator
│
├── transaction_storage.py          # Payment transactions & finance records (Firestore)
├── deposit_storage.py              # Municipal deposit/revenue categories
├── expense_storage.py              # Municipal expense categories
├── coa_storage.py                  # Chart of Accounts templates and account entries
├── entities_storage.py             # Municipal entities (offices, banks, units)
├── system_logs_storage.py          # Audit/activity logs with TTL management
│
├── routes/
│   ├── main_routes.py              # Auth, home, national dashboard
│   ├── api_routes.py               # REST API (OTP, register, login, applications)
│   ├── municipal_routes.py         # Municipal admin UI (HRM, accounting, operations)
│   ├── regional_routes.py          # Regional admin UI
│   ├── national_routes.py          # National admin UI
│   ├── superadmin_routes.py        # Super-admin UI
│   ├── municipal_api_logs.py       # Municipal data API (transactions, payroll, COA…)
│   ├── payments_routes.py          # Xendit invoice creation, webhook, PDF receipt
│   ├── permits_routes.py           # General permit applications (user)
│   ├── environment_routes.py       # Environmental clearance applications
│   ├── fisheries_routes.py         # Fisheries license applications
│   ├── forest_routes.py            # Forest resource license applications
│   ├── livestock_routes.py         # Livestock license applications
│   ├── wildlife_routes.py          # Wildlife license applications
│   ├── farm_routes.py              # Farm visit service requests
│   ├── service_routes.py           # General services (fertilizer, financial, compensation)
│   └── seminar_routes.py           # Seminar/training registrations
│
├── models/
│   ├── __init__.py
│   └── ph_locations.py             # Full Philippine province-to-municipality mapping
│
├── templates/
│   ├── home.html, login.html, signup.html
│   ├── create-municipal-admin.html
│   ├── create_regional_account.html
│   ├── payment-form.html, payment-success.html, payment-failed.html
│   ├── denr-print-preview.html
│   ├── account-disabled.html, auth_check.html, approval_status.html
│   ├── user/                       # Citizen portal (dashboard, profile, applications, permits, services)
│   ├── municipal/                  # Municipal admin (HRM, accounting, operations, logs)
│   ├── regional/                   # Regional admin (scoped dashboards, HR, accounting)
│   ├── national/                   # National admin (operations, HRM, logistics)
│   └── super-admin/                # Super-admin (global management, finance, regions)
│
├── static/
│   ├── css/                        # Stylesheets (auth, dashboard, denr-print, regional, seminar…)
│   ├── js/                         # JavaScript files
│   ├── images/                     # Image assets
│   └── uploads/                    # User-uploaded files
│
├── requirements.txt
├── firebase-credentials.json       # Firebase service account key (not committed)
└── .env                            # Environment variables (not committed)

Python 3.8+
pip
Firebase project (Firestore + Authentication + Storage)
Xendit account
Gmail account with App Password enabled

1. Clone the repository

   git clone https://github.com/alqzdave/TLPH.git
   cd TLPH

2. Create and activate a virtual environment

   python -m venv .venv
   .venv\Scripts\activate        # Windows
   source .venv/bin/activate     # macOS/Linux

3. Install dependencies

   pip install -r requirements.txt

4. Set up environment variables — create a .env file in the root directory:

   SECRET_KEY=your-secret-key
   MAIL_USERNAME=your-gmail@gmail.com
   MAIL_PASSWORD=your-app-password
   FIREBASE_API_KEY=your-firebase-api-key
   FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
   FIREBASE_DATABASE_URL=https://your-project.firebaseio.com
   FIREBASE_PROJECT_ID=your-project-id
   FIREBASE_STORAGE_BUCKET=your-project.appspot.com
   FIREBASE_MESSAGING_SENDER_ID=your-sender-id
   FIREBASE_APP_ID=your-app-id
   XENDIT_API_KEY=your-xendit-api-key
   XENDIT_PUBLIC_KEY=your-xendit-public-key

5. Place Firebase credentials

   • Download your service account key from the Firebase Console
   • Save it as firebase-credentials.json in the root directory

6. Run the application

   # Always use the virtual environment Python
   .venv\Scripts\python.exe app.py

   Note: Using .venv\Scripts\python.exe ensures all dependencies from the virtual environment are available. py app.py or python app.py may fail with import errors if the system Python is picked up instead.

7. Open the application

   http://localhost:5000
   

The application uses Gmail SMTP for OTP verification emails. To configure:

1. Enable 2-Factor Authentication on your Gmail account
2. Generate an App Password (Google Account → Security → App Passwords)
3. Add to .env:

   MAIL_USERNAME=your-email@gmail.com
   MAIL_PASSWORD=your-app-password

• Firebase Authentication with secure token management
• Server-side role enforcement (@role_required) on every protected route
• Email OTP with 10-minute expiry for registration verification
• All secrets isolated in .env (never hardcoded)
• Cache-control no-store headers prevent cached access after logout
• Disabled account detection at every page load
• Input validation at system boundaries (API routes and form handlers)
• HTTPS-ready for production deployment

.venv\Scripts\python.exe app.py
# Runs on http://localhost:5000 with debug mode enabled

1. Set debug=False in app.py
2. Configure all production environment variables in .env
3. Use a production WSGI server (e.g., Gunicorn or Waitress)
4. Set up HTTPS with SSL/TLS certificates
5. Switch Firebase and Xendit to their production configurations
6. Enable Firestore indexes as documented in REGIONAL_SYSTEM_LOGS_OPERATIONS.md

TLPH/
├── app.py
├── config.py
├── firebase_config.py
├── firebase_auth_middleware.py
├── transaction_storage.py
├── deposit_storage.py
├── expense_storage.py
├── coa_storage.py
├── entities_storage.py
├── system_logs_storage.py
├── requirements.txt
├── .env                            # (not committed)
├── firebase-credentials.json       # (not committed)
│
├── routes/                         # All Flask blueprints
├── models/                         # ph_locations.py
├── templates/                      # Jinja2 HTML templates per role
└── static/                         # CSS, JS, images, uploads

Special thanks to the DENR TLPH Team for their support and guidance throughout the development of this project.

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Contribution guidelines:

• Follow the existing code style and blueprint structure
• Write descriptive commit messages
• Test changes at all affected role levels
• Update relevant documentation files as needed
• Ensure Firebase and Xendit integrations are properly tested before submitting

• Firebase Setup Guide
• Firebase Setup Instructions
• Firebase Transactions Setup
• Xendit Payment Integration
• Payment System Overview
• DENR Print System
• Regional System Logs Operations
• Companies Schema
• Departments Schema
• Designations & Employees Schema

• Issue Tracker: Open an issue on GitHub
• Lead Developer: Mark Dave Alquiza — markdavemarasiganalquiza@gmail.com
• Repository: https://github.com/alqzdave/TLPH
• Organization: DENR TLPH Team

When reporting bugs please include: a description of the issue, steps to reproduce, expected vs. actual behavior, screenshots if applicable, and your browser/OS.

• Mobile application (iOS / Android)
• SMS notifications
• Advanced analytics dashboard
• Automated scheduled report generation
• Multi-language support (Filipino / English)
• Offline mode capability
• Data export (CSV / Excel)
• Enhanced search and filtering across all modules

This project is licensed under the MIT License — see the LICENSE file for details.

• Flask Documentation
• Firebase Documentation
• Xendit API Documentation
• Python-dotenv Documentation
• ReportLab Documentation

• DENR (Department of Environment and Natural Resources) - Project sponsor and stakeholder
• Firebase - Backend infrastructure and authentication
• Xendit - Payment gateway integration
• Flask Community - Web framework and ecosystem
• All contributors and team members who made this project possible

• v1.0 - Initial release with core features
  • User authentication and authorization
  • License and permit management
  • Payment integration
  • Inventory tracking
  • Transaction management

Made with ❤️ by the DENR TLPH Development Team

For more information or to contribute, visit our GitHub Repository