A local-first AI productivity workspace that combines multi-turn agent tool execution, executive daily briefings, and vector search over your notes.
Live Demo: https://lavoro.umeshshah.in
Walkthrough: Conversational streaming chat, morning briefing mode, and task creation.
flowchart LR
Browser["Frontend Shell<br/>(Vanilla ES Modules)"]
API["Express 5 Gateway<br/>(Auth, Rate Limit, Zod)"]
Orchestrator["AI Orchestrator<br/>(Gemini Agent Loop)"]
DB[("SQLite Storage<br/>(better-sqlite3 · WAL)")]
RAG["Vector Retrieval<br/>(Cosine Similarity)"]
Browser -->|"HTTP / SSE"| API
API --> Orchestrator
API --> DB
Orchestrator -->|"Function Calls"| DB
Orchestrator -->|"Semantic Query"| RAG
RAG --> DB
Tech stack: Node.js, Express 5, SQLite, Zod, JWT, Gemini, Docker, GitHub Actions.
The automated test suite runs 109 passing in-process tests plus 6 Playwright browser tests with 84.68% line coverage monitored via
c8.
- Multi-Turn Autonomous Agent Loop: Uses Gemini function calling with tools (
createTask,addReminder,createDailyPlan,searchProject,queryDocuments) and an offline deterministic fallback for development and CI testing. - Executive Morning Briefing & Day Planner: Aggregates time-blocked focus intervals, pending high-priority actions, and simulated urgent email triaging into a single daily dashboard.
- Embedded SQLite Persistence with WAL: Stores users, tasks, reminders, daily plans, and conversation histories in local SQLite (
better-sqlite3) across restarts, managed by 5 versioned SQL migrations. - Cryptographic Refresh Token Family Rotation: Persists only SHA-256 hashes of refresh tokens, rotates tokens on each refresh, and revokes the entire token family upon detecting reuse.
- In-Process Semantic Vector Search (RAG): Chunks text documents with 100-character overlaps and performs in-process cosine similarity searches over neural vector embeddings without external vector database dependencies.
- Hardened Sandboxed File Inspection: Enforces
path.resolveandfs.realpathchecks, a 200 KB size limit, extension whitelisting, sensitive file blocking (.env*,.key,.pem), and admin-role authorization. - Zero-Dependency Modular Frontend: Decomposed into 5 ES modules (
api.js,auth.js,chat.js,tasks.js,main.js) with safe DOM element construction that eliminates client-side XSS vulnerabilities.
git clone https://github.com/umeshkumar-git/lavoro.git
cd lavoro
npm install
npm --prefix backend installcp .env.example .envEdit .env to provide your configuration:
JWT_SECRET: Secret key for token signing (required; minimum 32 characters in production).DATABASE_URL:sqlite://./data/lavoro.db(enables file-backed persistence; falls back to in-memory if unset).GEMINI_API_KEY: Google Gemini API key (optional; defaults to the built-in deterministic demo provider if unset).ENABLE_PROJECT_TOOLS:trueorfalse(controls file inspection endpoints; defaults tofalsein production).
npm run migrate
npm run seedThis creates the database tables and seeds a development admin account:
- Email:
[email protected] - Password:
dev-seed-password-do-not-use-in-prod
# Start backend and serve frontend
npm startVisit http://localhost:10000 in your browser.
Lavoro uses Node.js's native test runner (node --test) and c8 for code coverage:
# Run unit and integration test suite (109 in-process tests)
npm test
# Run test suite with full coverage report (84.68% lines)
npm run test:coverage
# Run real browser end-to-end and accessibility tests (6 Playwright tests)
npx playwright test
# Run ESLint (flat config) and static asset verification
npm run lint
npm run typecheckCI runs automatically on all pull requests and pushes to main via GitHub Actions (.github/workflows/ci.yml), executing lint checks followed by the full test suite with coverage assertions.
Benchmarks were recorded using autocannon targeting an in-process Node.js instance on an 8-core Apple Silicon machine:
| Endpoint | Target Method | Requests/sec | Latency (p50) | Latency (p99) |
|---|---|---|---|---|
/api/health |
GET (Lightweight probe) | 3,840 req/s | 2.1 ms | 4.8 ms |
/api/dashboard/summary |
GET (In-Memory LRU Cached) | 2,910 req/s | 2.8 ms | 6.2 ms |
/api/tasks |
GET (SQLite Query) | 1,840 req/s | 4.3 ms | 11.2 ms |
/api/ai/chat |
POST (Demo Provider Loop) | 620 req/s | 14.1 ms | 32.5 ms |
Measurement Scope & Limitation: This benchmark isolates and measures local Express and SQLite processing overhead using the deterministic demo AI provider. It excludes upstream network latency to Google's Gemini API, which typically introduces 500–1200 ms of network round-trip and token generation latency depending on context size and prompt complexity.
-
Refresh Token Rotation: Refresh tokens are stored strictly as SHA-256 hashes with an assigned
family_id. Token reuse triggers automatic revocation of every active token in that family. -
File System Sandboxing: File read endpoints reject path traversals (
../,%2e%2e%2f), null bytes, symlinks pointing outside the project root, files$>200$ KB, and sensitive credential files (.env*,.pem,.key). -
Production Validation: The application refuses to start in
NODE_ENV=productionifJWT_SECRETis shorter than 32 characters, disables the development session reset endpoint, and enforces rate limits (5 attempts/min on auth, 60 requests/min general API). -
XSS Defense & Markdown Sanitization: Assistant replies are parsed with
marked(GFM tables enabled) and sanitized withDOMPurifybefore insertion; user messages are rendered exclusively throughtextContentwithout markdown parsing. - Sensitive Log Redaction: Pino structured logging automatically redacts Authorization headers, cookies, and request bodies, which reduces the risk of logging sensitive data (see tests/unit/logging.test.js).
- Single-Node SQLite: SQLite is embedded and designed for single-instance deployments. Horizontally scaling across multiple instances requires migrating to PostgreSQL.
- In-Memory Cache: The caching layer (
memoryCache.js) uses an in-process Map with TTL eviction, suitable for single-process deployments but not distributed nodes. - External Connectors: Calendar and email integration items in the daily briefing currently use mock providers rather than live OAuth sync with Google Workspace / Microsoft Graph.
- Add PostgreSQL adapter for horizontal container scaling.
- Implement OAuth 2.0 connectors for Google Calendar and Gmail sync.
- Add end-to-end integration tests using Playwright (verified markdown rendering, XSS sanitization, and axe-core accessibility).
- Implement multi-agent consensus verification for daily planning.
MIT License. See LICENSE for details.