eBOSS Sabangan

LGU Business One Stop Shop Platform
Business Applications, Mayor's Clearance, Treasury, and LGU Status in one system.

Quick Start · Screenshots · Project Layout · Technical Docs

Tip

Looking for maintainer-level details? Open docs/PROJECT_DOCUMENTATION.md.

Table of Contents

• At A Glance
• System Flowchart
• What This System Covers
• Screenshots
• Stack
• Quick Start
• Environment Variables
• Converter Service (DOCX to PDF)
• Run and Deploy
• Project Layout
• Troubleshooting

At A Glance

• Unified Mayors Office workspace for business permits, clearance processing, treasury, and status board operations.
• Document-heavy workflow support: DOCX generation, PDF conversion, and printable exports.
• Firebase-centered architecture with Next.js App Router APIs.
• Production path includes Firebase Hosting + Cloud Run converter service.

System Flowchart

flowchart LR
  subgraph Actors["Users and Portals"]
    mayorsOffice["Mayors Office (/)"]
    admin["Admin (/admin)"]
    treasury["Treasury (/treasury)"]
    public["Public (/lgu-status)"]
  end

  subgraph Web["Next.js Web App (App Router)"]
    ui["Client UI + Firebase Client SDK"]
    api["Route Handlers (app/api/*)"]
    templates["Document Templates (/templates)"]
    cache["Redis Preview Cache (optional)"]
    localjson["Local JSON routes (/api/local-users, /api/local-business)"]
  end

  subgraph Firebase["Firebase Platform"]
    auth["Firebase Auth"]
    rtdb["Realtime Database"]
    storage["Firebase Storage"]
  end

  subgraph Convert["Document Conversion Layer"]
    rewrite["Firebase Hosting rewrite (/api/convert/*)"]
    cloudrun["Cloud Run converter (LibreOffice)"]
    localconv["Local converter fallback (localhost:8080)"]
    wordcom["Windows fallback: Word COM (clearance PDF)"]
  end

  mayorsOffice --> ui
  admin --> ui
  treasury --> ui
  public --> ui

  ui <--> auth
  ui <--> rtdb
  ui --> api
  ui --> localjson

  api --> auth
  api --> rtdb
  api --> storage
  api --> templates
  api <--> cache

  api --> rewrite --> cloudrun
  api -. local fallback .-> localconv
  api -. clearance fallback .-> wordcom

Loading

• Main app pages use Firebase client SDK for real-time data and authentication.
• Protected/admin operations run through Next.js route handlers using Firebase Admin SDK token checks.
• Document exports render templates server-side, then convert via Cloud Run (with local/Windows fallbacks as needed).

What This System Covers

Mayors Office Portal (/)

• Mayors Office sign-in with Firebase Auth and verification checks.
• Business application review with filtering, status updates, and requirement validation.
• Requirement review workspace at /client/[id] with document approvals/rejections.
• Document workflows for DOCX preview, PDF conversion, merged output, and printing.
• Built-in messenger for Mayors Office-client communication.

Mayor's Clearance Workflow

• Clearance application and barangay requirement review.
• Approval/rejection with reason tracking.
• Yearly/monthly records generation and export-ready data support.

LGU Status Board (/lgu-status)

• Public office open/closed status and advisory notes.
• Mayor availability and expected return tracking.
• Featured event and upcoming events management.

Additional Portals

• /admin: user management and business application cleanup tools.
• /treasury: fee assessment, Cedula/OR handling, and client transaction processing.

Screenshots

Mayors Office Login	Treasury Login

Stack

Layer	Tech
Frontend	Next.js 15, React 18, TypeScript
UI	Tailwind CSS, Radix UI, lucide-react
API	Next.js Route Handlers (app/api/*)
Data/Auth	Firebase Realtime Database, Firebase Auth
Server Admin SDK	firebase-admin
Documents	docxtemplater, pizzip, pdf-lib, exceljs, docx-preview
Converter	Express + LibreOffice (cloud-run-converter)
Cache (optional)	Redis / Upstash-compatible URL

Quick Start

Prerequisites

• Node.js 22.x
• npm (or pnpm)
• Docker Desktop (for local converter)
• Firebase CLI (firebase-tools)
• Google Cloud SDK (gcloud) for Cloud Run deployment

Install

# root app
npm install

# converter service
cd cloud-run-converter
npm install
cd ..

Firebase CLI setup

firebase login
firebase use --add
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

Environment Variables

Create .env.local in the project root:

NEXT_PUBLIC_FIREBASE_DATABASE_NAMESPACE=users/webapp

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id
NEXT_PUBLIC_FIREBASE_DATABASE_URL=https://your-db-name.firebasedatabase.app

CONVERTER_SERVICE_URL=http://127.0.0.1:8080/convert/docx-to-pdf

# Optional cache
REDIS_URL=redis://user:password@host:6379
PREVIEW_FORM_CACHE_TTL_SECONDS=600
PREVIEW_FORM_CACHE_VERSION=1

Optional local admin SDK credentials (.env.development.local):

FIREBASE_ADMIN_SERVICE_ACCOUNT_PATH=C:\path\to\service-account.json
GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\service-account.json

Production-safe deployment .env sample:

NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_DATABASE_URL=https://your-db-name.firebasedatabase.app
CONVERTER_SERVICE_URL=https://converter-<hash>.asia-southeast1.run.app/convert/docx-to-pdf

Converter Service (DOCX to PDF)

The converter is a separate service under cloud-run-converter.

Cost note for production:

• If Cloud Run min-instances is set to 1 or higher, Google keeps the converter warm and bills idle time even when nobody is using the website.
• To stop idle billing and allow the service to scale to zero when unused, run:

gcloud run services update converter --region asia-south1 --min-instances=0

• This does not disable the converter. It only removes the always-on warm instance, so the first request after a quiet period may be slower because of a cold start.

Exposed endpoints:

• GET /health
• POST /convert/docx-to-pdf
• POST /convert/image-to-pdf
• POST /convert/images-to-pdf

Local Docker run:

cd cloud-run-converter
docker build -t eboss-converter .
docker run --rm -p 8080:8080 --name eboss-converter eboss-converter

Health check:

curl http://127.0.0.1:8080/health

Run and Deploy

Local development

npm run dev

Open:

• http://localhost:3000
• http://localhost:3000/lgu-status
• http://localhost:3000/admin
• http://localhost:3000/treasury

Production build

npm run build
npm run start

Firebase Hosting deploy

firebase deploy --only hosting

GitHub Repository Guide

Browse these first if you are reviewing the project on GitHub:

• README.md: onboarding and high-level overview
• docs/PROJECT_DOCUMENTATION.md: architecture, API map, and operations
• app: pages and API route handlers
• components: shared UI and reusable components
• database: Firebase data helpers
• lib: utilities and integration modules
• cloud-run-converter: DOCX/PDF conversion service
• public/templates: document templates

Project Layout

app/                    # Next.js App Router pages and API route handlers
components/             # Shared React components and UI primitives
database/               # Firebase Realtime Database data access helpers
lib/                    # Server/client utility modules and integrations
cloud-run-converter/    # LibreOffice conversion microservice
docs/screenshots/       # UI screenshots used in documentation
public/templates/       # Document templates and static files

Troubleshooting

• DOCX to PDF returns 500/502:
  • Verify converter health endpoint is reachable.
  • Verify CONVERTER_SERVICE_URL is valid.
• Firebase Admin initialization errors:
  • Set FIREBASE_ADMIN_SERVICE_ACCOUNT_PATH or FIREBASE_ADMIN_SERVICE_ACCOUNT_JSON.
• Missing database URL:
  • Set NEXT_PUBLIC_FIREBASE_DATABASE_URL.

---

For full architecture, API inventory, and maintenance runbook, see docs/PROJECT_DOCUMENTATION.md.