OwnerPilot - AI Operating Copilot for SMB Owners

Problem

Product scope

• India-first pharmacy and medical-store showcase with reusable SMB domain models for sales, purchases, products, expenses, recurring obligations, documents, actions, forecasts, and reorder plans.
• Dashboard surfaces revenue, margin, bills, inventory alerts, morning briefs, action queue, and quick-add entries for daily operations.
• Owner workflows include import preview and confirmation, recurring obligation tracking, document upload, AI investigation, action lifecycle management, forecasting, scenario planning, and cash-aware replenishment.

Architecture

• apps/web: Next.js App Router PWA with dashboard, imports, documents, Ask OwnerPilot, action center, planner, reorder plan, authentication, and workspace entry.
• apps/api: FastAPI service with Pydantic models for import jobs, document storage, investigations, briefings, forecasts, scenarios, quick-add ledger entries, actions, and scheduler runs.
• packages/contracts: shared schemas and structured response contracts to keep API/UI boundaries explicit.
• infra: Docker Compose stack with Postgres, pgvector, and Ollama for private self-hosted operation.

AI analyst workflow

• Investigation requests return structured summaries, confidence scores, evidence snippets, risks, recommendations, provider metadata, runtime mode, latency, and estimated cost.
• Retrieval-backed evidence is stored through the business document and pgvector memory path so recommendations can cite business context rather than acting like a free-form chatbot.
• Provider configuration supports local-open, BYO cloud, and hybrid modes so the project can demonstrate privacy-first local inference while still allowing hosted model fallbacks.
• Prompt guardrails and deterministic demo fixtures keep recruiter walkthroughs repeatable and safe to record.

Planning and action systems

• Cash-aware reorder planning blends stock, sales velocity, supplier costs, expiry risk, and recurring obligation pressure into replenishment recommendations.
• Forecast Lab exposes deterministic baseline forecasts and scenario outputs with assumptions and warnings instead of opaque chart-only results.
• Action Center tracks open, watching, snoozed, and resolved states so insights become operational tasks rather than static dashboard observations.
• Scheduler routes generate briefings, anomalies, due reminders, and action prompts that can evolve into daily owner workflows.

Engineering quality

• Monorepo structure separates UX composition, API orchestration, contracts, UI primitives, infra, and sanitized demo data.
• Public fixtures are sanitized and reproducible, with strict data safety rules against committing raw private business data.
• CI-oriented commands cover linting, type checking, web builds, API compile sanity, and formatting baselines across TypeScript and Python modules.
• Deployment docs cover both near-zero-cost hosted mode and private self-hosted Windows-first mode with Docker and Ollama.

Demo walkthrough

• Sample prompts: 'Why did profit drop this month?', 'What are my top selling products?', 'Which expense categories are spiking?', and 'What should I reorder next week?'
• Expected proof points: evidence-backed response, provider/mode/latency/cost metadata, visible action lifecycle, and deterministic forecast/scenario output.

Next steps

• Add API integration tests for import confirmation, recurring obligations, investigation, scheduler, and reorder workflows.
• Add Playwright smoke coverage for dashboard -> import -> ask -> action transitions.
• Expand import mapping presets, supplier lead-time settings, localization scaffolding, and model-routing observability.
• Capture a 90-second recruiter walkthrough and a 2-3 minute technical walkthrough for the project page media gallery.