Freshy

Freshy is a multi-component assistant that pairs a desktop experience with ingestion and orchestration services. This repo provides a runnable local scaffold for the desktop UI, ingestion API, and orchestrator API.

Prerequisites

• Python 3.11+ (for ingestion + orchestrator services)
• Node.js 18+ + npm (for the desktop UI)
• PowerShell 7+ (Windows run script)
• Optional: Local LLM runtime (e.g. Ollama) running at http://localhost:11434

Quick start (single command)

./run.sh

On Windows:

pwsh ./run.ps1

The run script will:

1. Copy .env.example to .env (first run only).
2. Install Python dependencies into .venv.
3. Install desktop app dependencies.
4. Launch:
   • Ingestion service on http://localhost:8001
   • Orchestrator service on http://localhost:8000
   • Desktop UI on http://localhost:5173

Set SKIP_INSTALL=1 if you want to run without reinstalling dependencies.

Configuration

Edit .env to point at your providers. By default it uses a local LLM:

LLM_PROVIDER=local
LOCAL_LLM_BASE_URL=http://localhost:11434

See .env.example for the full set of configuration options. Freshy is a local-first workspace for a multi-service digital avatar platform. This repository is intentionally minimal right now, with placeholder services and scripts that establish a consistent project layout and common developer workflow.

Repository layout

apps/
  desktop/              # Desktop client placeholder
services/
  orchestrator/         # Orchestrator service placeholder
  ingestion/            # Ingestion service placeholder
data/                   # Local-first data storage (gitignored in production)
docs/                   # Project documentation

Getting started

1. Prerequisites

• Bash (macOS/Linux) or PowerShell (Windows)
• Git
• Optional: Make (macOS/Linux)

2. Configure environment variables

Copy the example environment file and adjust values as needed:

cp .env.example .env

The defaults are tuned for local-first development and keep everything on localhost.

3. Run the workspace

Use whichever entrypoint matches your environment:

Bash (macOS/Linux)

./run.sh

PowerShell (Windows)

./run.ps1

Make

make run

The scripts currently print a summary of the intended services and ports. They are designed as a starting point for wiring up real services when they are added to the repository.

Scripts

Script	Purpose
run.sh	Local-first launcher for macOS/Linux
run.ps1	Local-first launcher for Windows
Makefile	Convenience targets for common tasks

Next steps

• Add application code under apps/desktop/.
• Add services under services/orchestrator/ and services/ingestion/.
• Expand the scripts to start real processes, containers, or task runners.

Documentation

Additional documentation lives in the docs/ directory.