Imported from Nanan-Holdings/VIZA-monorepo (viza-be/AGENTS.md). Install upstream with npx skills add Nanan-Holdings/VIZA-monorepo --skill viza-be. Copyright stays with the author.

Backend Agent Guide

Scope: this file applies to viza-be/**.

Purpose

viza-be owns the backend services for VIZA: AI visa assistance, RAG retrieval, application APIs, website automation support, submission automation, and Travel AI planning.

Components

• agent-backend: Express REST API, Socket.IO /visa, Drizzle migrations, RAG retrieval, form guidance, translations, validation, website automation support, and seed scripts.
• submission-service: Playwright queue runners for official visa portals, including DS-160 prefill and gated live submission, with health/wake HTTP endpoints, persisted recovery state and on-demand machine lifecycle.
• email-worker: Cloudflare Email Routing worker for applicant alias inboxes, Supabase/R2 ingestion, and forwarding official correspondence to the applicant's real email.
• resilience-worker: independent Cloudflare watchdog and encrypted server-to-server cache/outbox gateway. Its Durable Object stores only encrypted blobs and operational metadata; it does not decrypt applicant data.
• travel-service: Python FastAPI service for itineraries, revisions, flight/hotel options and Word/PDF export. Its independent /chat endpoint is not the current Web conversation entry; that coordinator runs in Next.js.

Ownership Boundaries

• Do not share runtime assumptions across services without documenting the boundary in viza-be/README.md.
• Database schema/migrations live in agent-backend.
• Website internal automation state, external status ingestion, packet handoff, OCR metadata, consent, and notification support live in agent-backend.
• Queue processing and browser automation live in submission-service.
• Travel generation and external travel APIs live in travel-service.
• Next.js UI/BFF changes live in viza-fe/internal-website, including current Travel conversation state coordination, form-assistant/OCR APIs and payment webhooks. Do not describe every Next API as a proxy to these services.

Validation

Run checks only for modified services:

cd viza-be\agent-backend
npm run type-check
npm run lint

cd ..\submission-service
npm run type-check

For travel-service, run the closest route smoke with uvicorn because there is no package-level type-check command.

Related Files

• viza-be/README.md
• viza-be/agent-backend/AGENTS.md
• viza-be/submission-service/AGENTS.md
• viza-be/travel-service/AGENTS.md
• viza-fe/README.md
• knowledge-base/visa-rag-seeds/README.md