{
  "markdown": "# HelpUDoc\n\nHelpUDoc is a multi-service workspace for research, drafting, and AI-assisted document workflows.\nThe repo currently combines:\n\n- a React + Vite frontend for the workspace UI, file editing, agent chat, and settings\n- an Express + TypeScript backend for auth, workspaces, files, knowledge, conversations, and admin APIs\n- a FastAPI-based Python agent service for Gemini-powered runs, skills, and on-demand document inspection\n- shared infrastructure manifests for local Docker Compose and GKE deployment\n\n## Repository layout\n\n| Path | What lives here |\n| ---- | --------------- |\n| `frontend/` | Main web app, including workspace, chat, file rendering, and settings pages. |\n| `backend/` | API server, persistence layer, auth/session handling, collaboration server, and admin endpoints. |\n| `agent/` | FastAPI agent runtime, prompt catalog, and on-demand document tools. |\n| `mobile/` | Expo-based mobile spike that currently proves shared-type reuse. |\n| `packages/contracts/` | Shared API and stream TypeScript types (`@helpudoc/contracts`). |\n| `packages/dashboard-runtime/` | Browser dashboard filters, aggregates, and Plotly payload helpers. |\n| `packages/shared/` | Compatibility re-exports forwarding to contracts and dashboard-runtime. |\n| `skills/` | Bundled skill prompts used by the agent runtime and editable through the settings flow. |\n| `infra/` | Docker Compose files, Cloud Build configs, and Kubernetes manifests. |\n| `env/` | Example environment files for local development and production deployment. |\n| `docs/` | Architecture, environment, deployment, and planning docs. |\n| `tests/` | Python regression and integration tests for the repo-level flows. |\n| `scripts/` | Helper scripts for local agent startup and pipeline checks. |\n\n## Quick start\n\n### Full stack with Docker Compose\n\n1. Create local env files:\n   ```bash\n   scripts/bootstrap_local_env.sh\n   ```\n2. Edit `env/local/stack.env` with local credentials, especially `GEMINI_API_KEY`.\n   The file is ignored by git and is the right place for machine-local secrets.\n3. Build and start everything from the repo root:\n   ```bash\n   docker compose -f infra/docker-compose.yml --env-file env/local/stack.env up --build\n   ```\n4. Open the local services:\n   - Frontend: `http://localhost:5173`\n   - Backend API: `http://localhost:3000/api`\n   - Agent service: `http://localhost:8001`\n   - Google Workspace MCP sidecar: `http://localhost:8000`\n   - MinIO API: `http://localhost:9000`\n   - MinIO console: `http://localhost:9001`\n\nTo stop the stack:\n\n```bash\ndocker compose -f infra/docker-compose.yml down\n```\n\nAdd `-v` if you also want to remove the named Docker volumes.\n\n## Local development\n\n### 1. Prepare env files\n\n```bash\nscripts/bootstrap_local_env.sh\n```\n\nThen edit `env/local/dev.env` and `env/local/stack.env` with local-only\ncredentials such as `GEMINI_API_KEY`, optional Google OAuth client credentials,\nand any hosted MCP URLs. Both files are ignored by git.\n\n### 2. Start shared dependencies only\n\n```bash\ndocker compose -f infra/docker-compose.dependencies.yml --env-file env/local/stack.env up -d\n```\n\nThis starts PostgreSQL, Redis, and MinIO with local on-disk data directories at the repo root (`.postgres-data/`, `.redis-data/`, `.minio-data/`).\n\n### 3. Run each service\n\nBackend:\n\n```bash\ncd backend\nnpm install\nENV_FILE=../env/local/dev.env npm run dev\n```\n\nFrontend:\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\nLocal QA without Google login:\n\n```bash\n# Backend: force local header auth instead of OIDC\ncd backend\nAUTH_MODE=headers ENV_FILE=../env/local/dev.env npm run dev\n\n# Frontend: show the local app instead of the Google sign-in screen\ncd frontend\nVITE_AUTH_MODE=headers npm run dev\n```\n\nFor browser automation, preload a local auth user in `localStorage` under\n`helpudoc-auth-user`. The Playwright clarification test already does this.\n\nAgent:\n\n```bash\ncd agent\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nENV_FILE=../env/local/dev.env uvicorn main:app --host 0.0.0.0 --port 8001 --reload\n```\n\nThe backend and agent both resolve `WORKSPACE_ROOT=backend/workspaces` and\n`SKILLS_ROOT=skills` relative to the repo root, so the local app should see the\nbundled skill catalog from `skills/`.\n\nOptional mobile app:\n\n```bash\ncd mobile\nnpm install\nnpm start\n```\n\n## Environment files\n\n- `env/local/dev.env.example`: values for running backend and agent directly from your shell\n- `env/local/stack.env.example`: values consumed by Docker Compose\n- `env/prod/config.env.example`: non-secret production config for Kubernetes\n- `env/prod/secrets.env.example`: production secrets template\n\nSee [docs/environment.md](docs/environment.md) for the full setup and auth notes.\n\n## Testing and verification\n\nRepo-level Python tests:\n\n```bash\npytest\n```\n\nFrontend linting and browser checks:\n\n```bash\ncd frontend\nnpm run lint\nnpm run e2e\n```\n\nTargeted scripts:\n\n- `backend/scripts/test_frontend_prompt_stream.mjs`\n- `backend/scripts/test_rag_hybrid_flow.mjs`\n- `backend/scripts/test_upload_rag_flow.mjs`\n\n## Key workflows in this repo\n\n- Workspace creation, file CRUD, and live collaborative editing\n- Agent chat with streaming updates, approvals, interrupt actions, and slash command metadata\n- Knowledge source management tied to workspaces\n- Admin settings for agent config, bundled skills, GitHub skill imports, and skill-builder sessions\n- Hybrid auth: local header-based development plus Google OAuth for delegated Google-backed tooling\n\n## Docs worth reading next\n\n- [docs/api/](docs/api/README.md) — API guides and reference\n- [docs/agent-self-evolution.md](docs/agent-self-evolution.md)\n- [docs/environment.md](docs/environment.md)\n- [docs/deploy.md](docs/deploy.md)\n- [docs/ci-cd.md](docs/ci-cd.md)\n- [frontend/README.md](frontend/README.md)\n- [backend/README.md](backend/README.md)\n- [agent/README.md](agent/README.md)\n- [infra/gke/README.md](infra/gke/README.md)\n",
  "bytes": 5913,
  "sha": "1c9930afa8e65356e9352d77dabbab61a279684b9fc06b4f06f033a5565f7d46",
  "repo_slug": "plc1220/helpudoc",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_plc1220_helpudoc_outputs_knowledge_okf_l_633dc179/readme"
}