Skip to content
umeshkumar-gitPublic

About

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Lavoro

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

Lavoro Demo Walkthrough Walkthrough: Conversational streaming chat, morning briefing mode, and task creation.


Architecture Overview

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
Loading

Tech stack: Node.js, Express 5, SQLite, Zod, JWT, Gemini, Docker, GitHub Actions.

CI The automated test suite runs 109 passing in-process tests plus 6 Playwright browser tests with 84.68% line coverage monitored via c8.


Key Features

  • 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.resolve and fs.realpath checks, 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.

Quick Start

1. Clone & Install Dependencies

git clone https://github.com/umeshkumar-git/lavoro.git
cd lavoro
npm install
npm --prefix backend install

2. Environment Configuration

cp .env.example .env

Edit .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: true or false (controls file inspection endpoints; defaults to false in production).

3. Run Migrations & Seed Database

npm run migrate
npm run seed

This creates the database tables and seeds a development admin account:

4. Start the Application

# Start backend and serve frontend
npm start

Visit http://localhost:10000 in your browser.


Testing and CI

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 typecheck

CI 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.


Performance and Latency

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.


Security Notes

  1. 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.
  2. File System Sandboxing: File read endpoints reject path traversals (../, %2e%2e%2f), null bytes, symlinks pointing outside the project root, files $&gt;200$ KB, and sensitive credential files (.env*, .pem, .key).
  3. Production Validation: The application refuses to start in NODE_ENV=production if JWT_SECRET is shorter than 32 characters, disables the development session reset endpoint, and enforces rate limits (5 attempts/min on auth, 60 requests/min general API).
  4. XSS Defense & Markdown Sanitization: Assistant replies are parsed with marked (GFM tables enabled) and sanitized with DOMPurify before insertion; user messages are rendered exclusively through textContent without markdown parsing.
  5. 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).

Known Limitations and Roadmap

Current Limitations

  • 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.

Roadmap

  • 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.

License

MIT License. See LICENSE for details.

About

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages