Architecture note
Available for software engineering roles - backend systems, production reliability, cloud deployment, and AI-assisted workflows.
NudgeAI is a local prototype/MVP foundation for turning scattered obligations into clear manual nudges that can be created, tracked, completed, snoozed, dismissed, and reopened.
01
Primary language: Python
Technologies: Python, JavaScript, HTML, CSS, Shell, TypeScript, Docker, Axios, FastAPI, Uvicorn, Mistral AI, FAISS, Sentence Transformers, ChromaDB, Pydantic, PyTorch, Docker Compose, GitHub Actions
Topics: Not specified
Last updated: 2026-10-22T00:34:43Z
Stars: 1
Forks: 0
Status: Active
Architecture note
Visual notes
NudgeAI is a local prototype/MVP foundation for turning scattered obligations into clear manual nudges that can be created, tracked, completed, snoozed, dismissed, and reopened.
Local prototype / MVP foundation. Not production-ready.
The canonical MVP backend is simple_api_server.py on port 8001. Existing MCP, RAG, Google data, and bridge files remain in the repository as experimental/legacy prototype work, but they are not required for the core manual nudge loop.
data/nudges.jsonFor the step-by-step local setup, run commands, API integration surface, and Hermes/MCP guidance, use:
docs/LOCAL_INTEGRATION_RUNBOOK.md
Recommended path:
python simple_api_server.py.frontend/: npm run dev.http://localhost:3000.data/*.json.Install Python dependencies:
pip install -r requirements.txt
Install frontend dependencies:
cd frontend
npm install
The manual nudge MVP does not require AI or Google credentials.
Optional variables:
NUDGE_STORE_PATH: override local nudge store path. Defaults to data/nudges.json.PLACES_STORE_PATH: override local places store path. Defaults to data/places.json.CONTEXT_RULES_STORE_PATH: override local context rules store path. Defaults to data/context_rules.json.RULE_STATE_STORE_PATH: override local context rule state store path. Defaults to data/rule_state.json.CURRENT_LOCATION_STORE_PATH: override local current location store path. Defaults to data/current_location.json.CALENDAR_AVAILABILITY_STORE_PATH: override local free/busy abstraction store path. Defaults to data/calendar_availability.json.VITE_USE_MOCK_DATA / REACT_APP_USE_MOCK_DATA: optional frontend mock-data flags. The core dashboard should use the real local API by default.HF_token, HF_MODEL, WHITECIRCLE_API_KEY: used only by experimental AI/MCP/RAG paths.GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI, GOOGLE_TOKEN, GOOGLE_APPLICATION_CREDENTIALS: used only by experimental local Google sync/OAuth helpers.MCP_SERVER_HOST, MCP_SERVER_PORT: used only by experimental Docker/MCP bridge paths.ELEVENLABS_API_KEY, GOOGLE_TTS_API_KEY: used only by optional demo asset generation scripts.LOG_LEVEL: optional logging control.Google OAuth token files such as token.json and drive_token.json must not be committed.
Never commit:
api/env.local.env*.env.localtoken.jsondrive_token.jsonCheck whether sensitive files are tracked:
git ls-files api/env.local
git ls-files token.json
git ls-files "*.env.local"
git ls-files calendar_events.json
git ls-files data_sync/calendar_sync.json
git ls-files data_sync/drive_sync.json
git ls-files data_sync/sync_summary.json
Historical verification cleanup finding: api/env.local, calendar_events.json, data_sync/calendar_sync.json, data_sync/drive_sync.json, and data_sync/sync_summary.json were identified as private artifacts that must stay out of git tracking.
Remove tracked private artifacts without deleting local files:
git rm --cached api/env.local
git rm --cached calendar_events.json
git rm --cached data_sync/calendar_sync.json
git rm --cached data_sync/drive_sync.json
git rm --cached data_sync/sync_summary.json
If these files are already untracked, do not re-add them. Rotate any exposed keys/tokens if they were ever committed or pushed. Removing a file from the latest commit is not enough if the secret exists in git history. If any real Google OAuth tokens, API keys, or provider credentials were ever committed, treat them as compromised.
Run the local privacy guard before committing:
python scripts/privacy_check.py
python scripts/nudgeai_health_check.py
The script fails if private Google sync outputs, OAuth tokens, or local env files are tracked by git. It warns, but does not fail, when those files merely exist locally and are ignored.
Backend:
python simple_api_server.py
Frontend:
cd frontend
npm run dev
Open the frontend at http://localhost:3000. The Vite dev server proxies /api to http://localhost:8001.
Backend syntax:
python -m py_compile simple_api_server.py mcp_api_bridge.py
Backend store tests:
python -m unittest discover -s tests -p "test_nudge*.py"
Frontend build:
cd frontend
npm ci
npm run build
GET /api/nudgesGET /api/nudges/summaryPOST /api/nudgesPATCH /api/nudges/{id}DELETE /api/nudges/{id}Supported filters on GET /api/nudges:
statusprioritydueTodayoverdueDELETE hard-deletes a local MVP nudge.
When a nudge is marked completed, completedAt is set. When a completed nudge is reopened or moved to another status, completedAt is cleared.
Core nudge MVP:
GET /healthGET /api/nudgesPOST /api/nudgesPATCH /api/nudges/{id}DELETE /api/nudges/{id}Experimental Google data endpoints:
GET /api/mcp/tools/query_calendarGET /api/mcp/tools/query_driveThe Google endpoints are experimental, local-only, and not production integrations.
NudgeAI includes experimental local Google Calendar and Google Drive sync utilities.
These utilities can fetch real local user data and serve it through local API endpoints:
GET /api/mcp/tools/query_calendarGET /api/mcp/tools/query_driveThis is not part of the production MVP path yet. The core MVP remains the manual nudge lifecycle.
The Google sync path is local-only and should be treated as sensitive because it may include:
Do not commit real synced Google data unless it has been explicitly sanitized.
Public demos should use fake fixture data from data/demo/, not private synced Google files.
Current sanitized fixtures:
data/demo/calendar_events.demo.jsondata/demo/drive_documents.demo.jsondata/demo/nudges.demo.jsondata/demo/places.demo.jsondata/demo/context_rules.demo.jsondata/demo/current_location.demo.jsondata/demo/calendar_availability.demo.jsonThese files use fake IDs, fake names, and demo-only metadata so they can support portfolio walkthroughs without exposing private Calendar or Drive data.
NudgeAI is pivoting toward private context-aware personal nudges, not booking SaaS. The first local rule is Gym Opportunity.
Current local/demo loop:
manual/demo location + manual calendar free minutes + local rule
-> evaluate context
-> create a normal nudge when the rule matches
The dashboard supports Location and Calendar source status cards, demo gym/far-away location controls, and a Check Context Rules Now action. This is not live background location, production Google Calendar, Health/Fit, Gmail, AI extraction, auth, or booking.
The next phase focuses on personal context rules: places, manual/demo location, calendar free/busy abstraction, and normal nudge creation when a rule matches. Booking remains optional later work. The manual nudge MVP remains the core product path.
Next field note
Open to software engineering roles across full-stack systems, platform and reliability work, workflow automation, and applied AI.
Write to Himanshu Lade →