HelpUDoc

HelpUDoc is a multi-service workspace for research, drafting, and AI-assisted document workflows. The repo currently combines:

• a React + Vite frontend for the workspace UI, file editing, agent chat, and settings
• an Express + TypeScript backend for auth, workspaces, files, knowledge, conversations, and admin APIs
• a FastAPI-based Python agent service for Gemini-powered runs, skills, and on-demand document inspection
• shared infrastructure manifests for local Docker Compose and GKE deployment

1. Create local env files:

   scripts/bootstrap_local_env.sh

2. Edit env/local/stack.env with local credentials, especially GEMINI_API_KEY. The file is ignored by git and is the right place for machine-local secrets.
3. Build and start everything from the repo root:

   docker compose -f infra/docker-compose.yml --env-file env/local/stack.env up --build

4. Open the local services:
   • Frontend: http://localhost:5173
   • Backend API: http://localhost:3000/api
   • Agent service: http://localhost:8001
   • Google Workspace MCP sidecar: http://localhost:8000
   • MinIO API: http://localhost:9000
   • MinIO console: http://localhost:9001

To stop the stack:

docker compose -f infra/docker-compose.yml down

Add -v if you also want to remove the named Docker volumes.

scripts/bootstrap_local_env.sh

Then edit env/local/dev.env and env/local/stack.env with local-only credentials such as GEMINI_API_KEY, optional Google OAuth client credentials, and any hosted MCP URLs. Both files are ignored by git.

docker compose -f infra/docker-compose.dependencies.yml --env-file env/local/stack.env up -d

This starts PostgreSQL, Redis, and MinIO with local on-disk data directories at the repo root (.postgres-data/, .redis-data/, .minio-data/).

Backend:

cd backend
npm install
ENV_FILE=../env/local/dev.env npm run dev

Frontend:

cd frontend
npm install
npm run dev

Local QA without Google login:

# Backend: force local header auth instead of OIDC
cd backend
AUTH_MODE=headers ENV_FILE=../env/local/dev.env npm run dev

# Frontend: show the local app instead of the Google sign-in screen
cd frontend
VITE_AUTH_MODE=headers npm run dev

For browser automation, preload a local auth user in localStorage under helpudoc-auth-user. The Playwright clarification test already does this.

Agent:

cd agent
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
ENV_FILE=../env/local/dev.env uvicorn main:app --host 0.0.0.0 --port 8001 --reload

The backend and agent both resolve WORKSPACE_ROOT=backend/workspaces and SKILLS_ROOT=skills relative to the repo root, so the local app should see the bundled skill catalog from skills/.

Optional mobile app:

cd mobile
npm install
npm start

• env/local/dev.env.example: values for running backend and agent directly from your shell
• env/local/stack.env.example: values consumed by Docker Compose
• env/prod/config.env.example: non-secret production config for Kubernetes
• env/prod/secrets.env.example: production secrets template

See docs/environment.md for the full setup and auth notes.

Repo-level Python tests:

pytest

Frontend linting and browser checks:

cd frontend
npm run lint
npm run e2e

Targeted scripts:

• backend/scripts/test_frontend_prompt_stream.mjs
• backend/scripts/test_rag_hybrid_flow.mjs
• backend/scripts/test_upload_rag_flow.mjs

• Workspace creation, file CRUD, and live collaborative editing
• Agent chat with streaming updates, approvals, interrupt actions, and slash command metadata
• Knowledge source management tied to workspaces
• Admin settings for agent config, bundled skills, GitHub skill imports, and skill-builder sessions
• Hybrid auth: local header-based development plus Google OAuth for delegated Google-backed tooling

• docs/api/ — API guides and reference
• docs/agent-self-evolution.md
• docs/environment.md
• docs/deploy.md
• docs/ci-cd.md
• frontend/README.md
• backend/README.md
• agent/README.md
• infra/gke/README.md