Skip to content

kanikaa-3018/PocketBuddy

BranchesTags
 
 

Repository files navigation

PocketBuddy

Campus financial guard for Indian students.

Passive UPI tracking, spending runway, companion Android sync, cart pooling, campus food intelligence, travel guidance, and AI-assisted nudges.

Live Web App  |  Download Android Connector  |  Repo APK  |  Product Requirements  |  AWS Runbook

Stack AWS Android

Contents

Overview

PocketBuddy is a hackathon prototype for students who spend through UPI, hostel food counters, subscriptions, quick-commerce orders, and shared room purchases. The product is designed around a low-friction first step: connect the Android phone once, let supported UPI/SMS notifications sync in the background, and turn that raw payment stream into useful financial context.

The platform combines:

  • passive transaction capture from Android notifications;
  • spending runway and dashboard insights;
  • transaction review and categorization;
  • companion-device setup and sync logs;
  • quick-commerce cart pooling;
  • campus food and travel guidance;
  • Amazon Bedrock powered AI support where enabled;
  • AWS-hosted demo infrastructure.

Demo Links

Surface Link
Web app https://d3g6cg7q9hn7hi.cloudfront.net/
Android connector APK, hosted PocketBuddy-Connector-v0.1.0.apk
Android connector APK, repo copy android/releases/PocketBuddy-Connector-v0.1.0.apk
Mobile ingest endpoint CloudFront webhook route
AWS deployment guide docs/aws-e2e-deployment-runbook.md
Mobile ingest contract docs/mobile-ingest-contract.md

The Android APK is a sideloaded hackathon build. Android or Google Play Protect can warn because it is not distributed through Play Store and it requests notification access. Use only the hosted APK or the repository APK linked above.

What Is Built

Module Status Details
Authentication Built Signup/login flow with user profile state.
Onboarding Built Student context, campus details, and preference capture.
Dashboard Built Cycle spend, runway, transactions, and feature entry points.
Transactions Built List, review, category handling, and normalized UPI events.
Android Connector Built Native Kotlin app that captures supported payment/SMS notifications.
Companion Device Built APK download, config copy, sync testing, and recent activity details.
Mobile Ingest Built Webhook path through CloudFront, API Gateway, Lambda, SQS, and DynamoDB.
Cart Pooling Built Quick-commerce pool flow and split-management UI.
Food Intelligence Built Campus food data and recommendation endpoints.
Travel Guidance Built/early Route/fare guidance exists; scale path is crowdsourced fare medians.
Bedrock/Nova Built Backend supports Amazon Nova Lite through Bedrock runtime when enabled.
AWS Hosting Built CloudFront/S3 frontend, EC2 backend, serverless ingest pipeline.

User Flow

Student creates account
  -> completes onboarding
  -> opens Companion Device page
  -> downloads Android Connector APK
  -> taps One-Tap Auto Configure on the Android phone
  -> connector opens with server/account fields filled
  -> enables notification access
  -> supported UPI/SMS alerts sync into PocketBuddy
  -> dashboard, transactions, pools, and insights update

AWS Architecture

The deployed demo uses AWS in two layers:

  1. Web application path for the student-facing platform.
  2. Serverless ingest path for mobile payment events.

PocketBuddy AWS architecture 

Browser
  -> CloudFront
      -> S3 origin for React/Vite frontend assets
      -> EC2 origin for /api/* backend routes
      -> API Gateway origin for /api/ingest/notification-v2

Android Connector
  -> CloudFront /api/ingest/notification-v2
  -> API Gateway HTTP API
  -> Lambda ingest
  -> SQS queue
  -> Lambda processor
  -> DynamoDB ingest ledger

Main Backend
  -> EC2 Ubuntu
  -> Nginx reverse proxy
  -> FastAPI service
  -> MongoDB Atlas
  -> Amazon Bedrock Runtime when AI is enabled

AWS Service Map

AWS service Current role
Amazon S3 Stores frontend build output and downloadable APK artifact.
Amazon CloudFront Public HTTPS entrypoint for frontend, API routing, and APK download.
Amazon EC2 Runs the main FastAPI backend behind Nginx.
Amazon API Gateway Receives mobile notification webhooks.
AWS Lambda Queues and processes serverless ingest events.
Amazon SQS Buffers mobile notification events.
Amazon DynamoDB Stores serverless ingest ledger records.
Amazon Bedrock Provides Nova Lite AI generation when enabled.
Amazon CloudWatch Logs and metrics for Lambda, SQS, EC2, and Nginx/service debugging.
AWS Budgets Hackathon account cost guardrails.

See the full AWS runbook: docs/aws-e2e-deployment-runbook.md.

Repository Layout

PocketBuddy/
  android/                 Native Android connector Gradle project
  backend/                 FastAPI backend
  data/                    Demo/default data and seedable datasets
  docs/                    PRD, AWS runbooks, architecture, contracts, plans
  frontend/                React + Vite web application
  public/                  Static public assets

Tech Stack

Layer Technology Purpose
Frontend React 19, Vite, TypeScript, TanStack Router, TanStack Query, Tailwind CSS, Lucide Student web app, dashboards, forms, onboarding, companion setup, pool UI
Backend Python, FastAPI, Pydantic, Motor, PyMongo, Boto3 Auth, profile, transactions, pools, food, travel, AI routes
Database MongoDB Atlas, DynamoDB Main product data in MongoDB; serverless ingest ledger in DynamoDB
Android Kotlin, Android Gradle Plugin, NotificationListenerService, OkHttp Payment/SMS notification capture and webhook sync
Cloud CloudFront, S3, EC2, API Gateway, Lambda, SQS, Bedrock, CloudWatch Hosted demo, static assets, serverless ingest, AI, logs

Local Development

1. Install frontend dependencies 
cd "C:\Users\nhnis\Desktop\Amazon Hackon\PocketBuddy\PocketBuddy"
npm.cmd install
2. Configure backend environment 
cd backend
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item .env.example .env

Edit backend/.env:

JWT_SECRET=<long-random-secret>
MONGO_URI=<mongodb-atlas-or-local-uri>
PORT=8000
AWS_REGION=ap-south-1
BEDROCK_ENABLED=false
BEDROCK_MODEL_ID=amazon.nova-lite-v1:0

Keep .env local. Do not commit secrets.

3. Run backend 
cd "C:\Users\nhnis\Desktop\Amazon Hackon\PocketBuddy\PocketBuddy\backend"
.\.venv\Scripts\Activate.ps1
uvicorn app.main:app --reload --port 8000
4. Run frontend 
cd "C:\Users\nhnis\Desktop\Amazon Hackon\PocketBuddy\PocketBuddy"
npm.cmd run dev --workspace=frontend

Open the local URL printed by Vite.

Android Connector

The Android module is documented in android/README.md.

Install The Demo APK

Use either of these links on the Android phone that receives UPI/SMS alerts:

If Android blocks installation:

  1. Open Play Store.
  2. Tap profile icon.
  3. Open Play Protect.
  4. Open settings.
  5. Temporarily disable app scanning.
  6. Install PocketBuddy Connector from one of the links above.
  7. Turn Play Protect scanning back on.

This is only for the hackathon sideload build. Do not ask users to keep Play Protect disabled.

Build The Android Connector Locally

cd "C:\Users\nhnis\Desktop\Amazon Hackon\PocketBuddy\PocketBuddy"

$env:JAVA_HOME = "C:\Program Files\Android\Android Studio\jbr"
$env:Path = "$env:JAVA_HOME\bin;$env:LOCALAPPDATA\Android\Sdk\platform-tools;$env:Path"

.\android\gradlew.bat -p android :connector:testDebugUnitTest :connector:assembleDebug

Install with ADB:

$ADB = "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe"
$DEVICE = "10BF821N3M0055M"

& $ADB -s $DEVICE install -r .\android\connector\build\outputs\apk\debug\connector-debug.apk

Companion Device Setup

  1. Login to the web app.
  2. Open Settings -> Companion Device.
  3. Download the Android APK from the install card.
  4. Open PocketBuddy web on the Android phone and tap One-Tap Auto Configure.
  5. Confirm the connector shows the linked account.
  6. Open notification access settings from the app.
  7. Enable notification access for PocketBuddy Connector.
  8. Make a small UPI transaction or use a debug broadcast.
  9. Return to the web app and check Recent Sync Activity.

If the app link cannot open the connector, use Copy fallback config from the Companion Device page.

Verification Commands

Check Command
Frontend type-check npm.cmd run check --workspace=frontend
Frontend build npm.cmd run build --workspace=frontend
Backend syntax python -m compileall backend\app
Android tests/build .\android\gradlew.bat -p android :connector:testDebugUnitTest :connector:assembleDebug
Git whitespace git diff --check

Deployment Notes

Frontend deployment to S3 and CloudFront

Build:

npm.cmd run build --workspace=frontend

Upload the contents of:

frontend/dist/

to:

s3://pocketbuddy-frontend-734705208425-ap-south-1/

Create a CloudFront invalidation:

/*
Backend deployment on EC2 
cd /home/ubuntu/PocketBuddy
git pull --ff-only origin main
cd backend
.venv/bin/pip install -r requirements.txt
sudo systemctl restart pocketbuddy-backend
sudo systemctl status pocketbuddy-backend --no-pager
Android APK artifact

Store the signed APK at:

s3://pocketbuddy-frontend-734705208425-ap-south-1/downloads/PocketBuddy-Connector-v0.1.0.apk

Public URL:

https://d3g6cg7q9hn7hi.cloudfront.net/downloads/PocketBuddy-Connector-v0.1.0.apk

Repository copy:

android/releases/PocketBuddy-Connector-v0.1.0.apk

Do not share unsigned or intermediate APK files such as:

PocketBuddy-Connector-v0.1.0-release-aligned.apk

Do not commit local signing material or scratch artifacts such as:

scratch/android-signing/*.jks
scratch/android-signing/*password*
scratch/android-release/*.idsig

Security And Privacy

  • Never commit .env, keystores, MongoDB passwords, JWT secrets, AWS credentials, or local signing passwords.
  • Keep Android notification access transparent to users; the connector exists only to detect supported payment/SMS alerts.
  • Mask account numbers, phone numbers, UTRs, and links before showing notification previews.
  • Keep Play Protect disabled only temporarily when installing the known hackathon APK.
  • Use server-side idempotency for mobile events to avoid duplicate transactions.
  • Keep AWS Budgets and billing alerts enabled while demo resources are active.

Roadmap

PocketBuddy should keep useful demo defaults without becoming hardcoded to one campus or one user.

Area Next step
Food data Menu photo scanner using S3, Textract, Nova Lite, and student verification votes.
Travel Crowdsourced route medians plus current booking-app quote input for surge-aware negotiation targets.
Categories Parent category model with custom user labels for clean analytics.
Subscriptions Interval clustering to detect recurring merchants beyond static service lists.
Parser quality Feedback loop for failed or low-confidence SMS/notification formats.
Cart pools Auto-verify roommate repayments from incoming UPI credit notifications.

Project Docs

Document Purpose
docs/Initial-PRD.md Original product requirements and feature framing.
docs/aws-e2e-deployment-runbook.md Full AWS deployment notes and configuration.
docs/aws-low-cost-setup.md Beginner AWS cost-safety guide.
docs/mobile-ingest-contract.md Android-to-backend webhook contract.
docs/final-architecture-decisions.md Current architecture decisions.
android/README.md Android connector setup, build, and test guide.

License

Hackathon prototype. Add a production license before public open-source release.

About

d3g6cg7q9hn7hi.cloudfront.net/

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • TypeScript 65.4%
  • Python 29.8%
  • Kotlin 4.1%
  • Other 0.7%