Getting Started

Repository layout

The local workspace expects two sibling repositories:

• D:/AI/arabic-itsm-desk: this monorepo for web, API, shared package, migrations, and docs.
• D:/AI/arabic-itsm-server: the classifier service used by the API.

Prerequisites

• Node.js 20+
• pnpm 10+
• Python 3.10+ for the classifier service
• Docker Desktop for the local Supabase stack

Core workspace commands

Command	Purpose
pnpm install	Install workspace dependencies
pnpm setup:env	Create .env and .env.local from defaults
pnpm dev:web	Run the Vite web app on port 3000
pnpm dev:api	Run the Hono API on port 3001
pnpm dev:classifier	Run the sibling FastAPI classifier
pnpm dev:stack	Start Supabase, migrate, then run classifier, API, and web
pnpm build	Build every workspace package, including docs
pnpm docs:dev	Run the VitePress docs package
pnpm docs:build	Build the VitePress docs package

Environment model

The API loads environment files in this order:

1. repo root .env
2. repo root .env.local
3. apps/api/.env
4. apps/api/.env.local

The web app reads root .env* through Vite.

Minimum environment values

API and Supabase

SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
API_PORT=3001
API_CORS_ORIGIN=http://localhost:3000
CLASSIFIER_URL=http://localhost:8000
CLASSIFIER_MODEL_ID=marbert_l2_best
DEMO_USER_PASSWORD=Demo@1234

Web

VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=
VITE_API_URL=http://localhost:3001

Typical local startup

1. Run pnpm install.
2. Run pnpm setup:env.
3. Start the database with pnpm supabase:start.
4. Apply migrations with pnpm supabase:migrate.
5. Seed demo data with pnpm seed:users and pnpm seed:tickets.
6. Start the full stack with pnpm dev:stack.

Health checks

• Web UI: http://localhost:3000
• API: http://localhost:3001/health
• Classifier: http://127.0.0.1:8000/api/health

Docs package notes

The documentation package lives at packages/docs. It is intentionally static and isolated from the production app runtime. If vitepress is not already installed in the workspace, run pnpm install after pulling these changes before using pnpm docs:dev.