Nargis

Voice-first AI productivity companion

Nargis is a full-stack demo of a voice-first AI productivity assistant (tasks, habits, journaling) with a real-time pipeline and a dual-mode AI backend (API + local fallback).

Nargis is a polyglot monorepo for a productivity assistant with a Next.js web app, a FastAPI orchestrator, and a Go gateway for realtime traffic.

Quick Start

Prerequisites: Bun, Python 3.12, uv, Go, and a POSIX-compatible shell.

bun install
bun dev

Local defaults:

• Web: http://localhost:3000
• Python API: http://localhost:8000
• Go gateway: ws://localhost:8080

Root Scripts

Command	Purpose
bun dev	Start the web app, Python API, and Go gateway together
bun run build	Build the web app and Go gateway
bun lint	Preferred cleanup/write command across the repo
bun qa	Fast one-stop validation alias
bun run test	Run all test suites
bun smoke:ws	Run the websocket smoke client
bun smoke:local-realtime	Run the local realtime smoke script

Targeted escape hatches remain available:

• dev:web, dev:py, dev:go
• build:web, build:go
• test:web, test:api, test:go
• lint:web, lint:api, lint:go

Repo Guide

• PLANNING.md: project intent, goals, and success criteria
• ARCHITECTURE.md: system design, boundaries, and technical decisions
• ROADMAP.md: delivery phases and next work
• CONTRIBUTING.md: contribution workflow
• docs/DEPLOYMENT.md: deployment runbook
• docs/PRODUCTION_CHECKLIST.md: production readiness checklist

Apps

• apps/web/README.md: frontend-specific setup and workflow
• apps/api-py/README.md: Python API setup and runtime notes
• apps/core-go/README.md: Go gateway setup and runtime notes

Author

Divij Ganjoo

• Portfolio: divijganjoo.me
• LinkedIn: in/divij-ganjoo
• GitHub: @divijg19

Built with ❤️ and ☕ as a demonstration of modern full-stack development with AI/ML integration.