DocsOverviewHow It Works

How It Works

A deep dive into Nareli's architecture, local-first data philosophy, AI suggestion pipeline, and privacy-first design. Understand what happens under the hood when you track time, receive suggestions, and generate reports.

Architecture Overview

Nareli is a desktop-first application built with Tauri, combining a native macOS shell with a React-based interface. Unlike browser-based time trackers that depend on cloud servers, Nareli runs entirely on your Mac. The app consists of two main components: a lightweight Bun-powered server that manages your data, and a Tauri frontend that provides the user interface. The server process starts automatically when you launch Nareli and listens on a local port. It exposes a GraphQL API that the frontend uses to query and mutate data. This architecture means your data never traverses the internet — all communication happens over localhost. The server also handles background processing tasks like Slack polling, activity analysis, and recurring task generation. The frontend is built with React 18 and uses Apollo Client for GraphQL communication, including real-time subscriptions via WebSocket. Zustand manages local UI state like sidebar visibility and filter preferences. The interface is fully responsive within the desktop window and supports both light and dark modes.

The local server architecture means Nareli works offline. Your data is always accessible, even without an internet connection.

The Nareli Workflow

Nareli follows a continuous improvement cycle: Track → Analyze → Suggest → Improve. You start by tracking your time manually using the floating timer bar or by creating time entries directly. As you work, Nareli observes patterns — which tasks you work on, when you start and stop, and how you allocate time across projects. The analysis phase happens in the background. Nareli's activity analysis processor runs periodically, examining your desktop activity and correlating it with your existing tasks and projects. The Slack integration adds another data source, monitoring your workspace messages for mentions of tasks, deadlines, and work-related discussions. Based on this analysis, Nareli generates intelligent suggestions. These might be new time entries you forgot to log, tasks that should be created based on Slack conversations, or updates to existing tasks. You review each suggestion and accept or decline it with a single click. Over time, Nareli learns from your decisions, improving the relevance of future suggestions. The improvement phase comes naturally as you build a comprehensive picture of how you spend your time. Dashboard charts reveal productivity trends, reports show billable utilization rates, and goal tracking keeps you accountable. Each week's data feeds into the next cycle, making Nareli progressively more useful the longer you use it.

Suggestions are never applied automatically. You always have full control over what gets added to your timeline.

Data Storage and Privacy

All your data lives in two SQLite databases stored locally on your Mac. The primary database (local.db) contains your business data: clients, projects, tasks, time entries, activities, suggestions, and learnings. The secondary database (cache.db) holds temporary data like Slack message caches and rate limit tracking. Both databases are stored in ~/Library/Application Support/Nareli/ in production. Nareli never sends your work data — time entries, tasks, client information, project details, or any content from your Slack messages — to any external server. The only network communication is license verification, which transmits only your license key and a machine identifier. Even AI processing happens locally through Ollama, meaning your activity data and Slack messages are analyzed entirely on your hardware. The SQLite databases use a straightforward schema with no complex migrations. Tables are created with CREATE TABLE IF NOT EXISTS statements, ensuring the database self-heals if tables are missing. This design also makes it trivial to back up your data — simply copy the .db files to another location. Time Machine automatically includes these files in your regular backups. For sensitive credentials like API tokens, Nareli uses the macOS Keychain rather than storing them in plain text. Your Slack tokens, Ollama configuration, and license keys are all secured through the system keychain, benefiting from macOS's hardware-backed encryption on Apple Silicon Macs.

You can find your databases at ~/Library/Application Support/Nareli/. Copy these files to back up all your Nareli data.

How AI Suggestions Work

Nareli's AI suggestion system uses Ollama, an open-source local LLM runtime, to analyze your work patterns and generate actionable suggestions. When you install and configure Ollama, Nareli connects to it over localhost — your data never leaves your machine, even during AI processing. The suggestion pipeline processes two primary data sources. First, the Slack integration polls your workspace channels for new messages, caches them locally, and sends batches to the local LLM for analysis. The AI identifies mentions of tasks, deadlines, project updates, and other work-relevant information, then generates suggestions like "Create task: Update API documentation (mentioned in #engineering)" or "Log 45 minutes for client meeting (discussed in #client-acme)". Second, the activity analysis processor monitors your desktop activity at regular intervals. It correlates application usage, window titles, and active durations with your existing projects and tasks. If it detects that you spent 90 minutes in VS Code working on files in a specific project directory, it might suggest a time entry for that project. Each suggestion has a type — task_create, task_update, info, or timeentry_create — and starts with a "pending" status. You review suggestions in the Suggestions page or through system notifications, then accept or decline each one. Accepted suggestions are automatically applied: tasks are created or updated, and time entries are added to your timeline. Declined suggestions help train the system to avoid similar irrelevant suggestions in the future.

Suggestion types:
  task_create      → Creates a new task
  task_update      → Updates an existing task
  info             → Informational insight
  timeentry_create → Creates a time entry

Server Communication

Nareli is designed to minimize network dependencies. The only external server communication is license verification, which happens during initial activation and periodically thereafter. These verification requests contain only your license key and a hashed machine identifier — no usage data, time entries, task information, or any other personal content is transmitted. The license server validates that your key is active and has not exceeded its device limit (two Macs per license). If your Mac is offline during a periodic check, Nareli uses a cached validation and continues operating normally. The app is designed to work offline for extended periods without any degradation in functionality. All other communication happens locally. The Tauri frontend communicates with the Bun server over localhost using GraphQL over HTTP and WebSocket. If you use the Slack integration, Nareli communicates directly with the Slack API from your machine using your personal OAuth tokens — these connections go from your Mac to Slack's servers, not through any Nareli infrastructure. This architecture ensures that even if Nareli's servers were to go offline, your app would continue working exactly as before. The only feature that requires internet access is the initial license activation. Everything else — time tracking, task management, AI suggestions, reports, and data storage — functions entirely offline.

Nareli does not collect analytics, telemetry, or usage data of any kind. Your workflow is private by design.

Real-Time Updates

Nareli uses a GraphQL subscription system built on an in-memory EventEmitter-based PubSub to deliver real-time updates throughout the interface. When a background process creates a new suggestion, updates queue statistics, or completes an analysis batch, the frontend receives the update instantly without polling. The system status indicator in the sidebar reflects live processing state. When Slack messages are being analyzed or desktop activity is being processed, you'll see the indicator animate and display current queue depths. This transparency lets you know when Nareli is actively working on generating suggestions versus when it's idle. System notifications integrate with macOS's native notification system through Tauri. When a new suggestion is created — for example, a recommended time entry based on detected Slack activity — you receive a toast notification that you can click to jump directly to the Suggestions page for review. These notifications respect your macOS Do Not Disturb settings and can be disabled independently in Nareli's Settings.

Real-time subscriptions work over a local WebSocket connection. No external push notification service is used.