CivicAPI

• 

  CivicAPI Project

• 

  Health Check of the API

• 

  Bills process through API

• 

  Bills Process after entered

• 

  All-Bills

• 

  Notify using Vonage or direct console

Inspiration

CivicAPI was inspired by the everyday challenge citizens face in keeping track of utility bills. Many households and organizations still depend on fragmented systems (paper, email, SMS) that are easy to miss. We wanted to build a unified API + lightweight UI that lets people upload bills, extract key info, and send reminders — all with open-source simplicity.

What it does

(a) Upload bills via PDF, text, or form

(b) Auto-extract vendor, amount, and due date (mock NLP parser)

(c) Store bills in a lightweight SQLite database

(d) Query bills by status (unpaid, paid, canceled)

(e) Mark bills as paid with one click/API call

(f) Send reminders via SMS/WhatsApp/console fallback

(g) Secure API access with x-api-key

(h) Optional UI for uploading/viewing bills and triggering notifications

How we built it

Backend: Python + FastAPI (running on Uvicorn)

Database: SQLite3 (portable + easy)

Frontend: Minimal HTML + JS (no framework, “Massive UI” style demo)

Notifications: Vonage API (SMS/WhatsApp) with fallback logging

Parsing: PyPDF + regex-based mock parser for demo

Deployment: AlmaLinux on Namecheap VPS, systemd service on port 4051

Challenges we ran into

(i) Debugging FastAPI dependency injection (Depends) while enforcing API keys (ii) Handling SQLite permission issues in production (readonly database) (iii) Keeping the hackathon scope small but demo-friendly (simple UI + curl examples) (iv) Ensuring that SMS/WhatsApp fallbacks worked when API keys weren’t set

Accomplishments that we're proud of

(a) Live, running service accessible at http://162.0.225.90:4051/ (b) Both curl CLI testing and browser UI demo working (c) Clean fallback system — works even without Vonage creds (d) Easy local deployment (one systemctl service, SQLite backend)

What we learned

(i) Building APIs quickly with FastAPI + SQLite is extremely productive (ii) System-level deployment details (systemd, venv, DB paths) matter a lot (iii) Hackathon projects need both technical strength and clear demos (iii) Judges love seeing a real UI in addition to APIs

What's next for CivicAPI

Smarter bill parsing using LLMs (e.g. GPT-based invoice extraction) Multi-user accounts with cloud DB (Postgres / TiDB Serverless) Real-time email ingestion → auto-bill creation Richer UI (React-based dashboard + charts) Open-sourcing as a Civic Tech utility for NGOs and smart cities

Built With

• almalinux
• fastapi
• html
• javascript
• pypdf
• python
• sqlite
• systemd
• uvicorn
• vonageapi