Local Development

Set up ExtractForm on your machine for development and testing.

Prerequisites

• Node.js 18+
• MongoDB (local or Docker)
• Redis (for job queue)
• ChromaDB (optional, for RAG on large documents)

MongoDB with Compass

1. Start MongoDB locally.

2. In Compass, connect with the same URI as in .env:

   mongodb://localhost:27017/extract_form

3. Run npx prisma db push once to create collections.

4. Start the API — Compass shows Job, Schema, User, etc. as they are created.

Other services

Service	Port	.env variable
Redis	6379	REDIS_URL=redis://localhost:6379
Chroma	8000	CHROMA_URL=http://localhost:8000
MinIO (optional)	9000	S3_ENDPOINT=http://localhost:9000

Run the backend

cd extractForm_back
cp .env.example .env
npm install --legacy-peer-deps
npx prisma db push
npm run start:dev

• API: http://localhost:4000
• Swagger: http://localhost:4000/api/docs

Default storage is local files (STORAGE_DRIVER=local, ./uploads).

Architecture

There are no separate worker binaries. One NestJS process handles everything:

npm run start:dev
    ├── HTTP API (controllers)
    ├── Job consumer (BullMQ / Redis)
    ├── Webhook delivery consumer
    ├── Import queue consumer
    └── Cron (job expiry, integration sync)

Redis + BullMQ coordinate jobs if you run multiple instances later. For local development, a single process is sufficient.

Frontend (optional)

The React frontend runs separately:

cd extractForm_front
npm install
npm run dev

• Frontend: http://localhost:3000
• Proxies /api and /uploads to http://localhost:4000
• In-app help links point to the documentation site (configure with VITE_DOCS_URL in .env)

Run the documentation site

cd extractForm_docs
npm install
npm run start

• Docs: http://localhost:3001 (port 3001 avoids conflict with the frontend on 3000)
• Links to the dashboard via APP_URL (defaults to https://structaai.online; set APP_URL=http://localhost:3000 for local dev)

To regenerate API reference pages after backend changes:

# In extractForm_back
npm run openapi:export

# In extractForm_docs
npm run gen-api-docs

Key environment variables

See .env.example in the backend repository for the full list. Minimum for local dev:

DATABASE_URL=mongodb://localhost:27017/extract_form
REDIS_URL=redis://localhost:6379
JWT_ACCESS_SECRET=dev-secret-change-in-production
PORT=4000
CORS_ORIGINS=http://localhost:3000
FRONTEND_URL=http://localhost:3000

Production deployment

For production on a VPS with Docker, see Production Deployment.

Production stack lives in structaai/deploy/ (see README.md in that folder).

Production URLs:

Service	URL
Dashboard	https://structaai.online
Documentation	https://docs.structaai.online
API (proxied)	https://structaai.online/api

Quick deploy:

cd structaai/deploy
cp .env.example .env   # fill secrets
./scripts/deploy.sh