agent-context

FaceKom Agent Quick Context

Agent Onboarding

Read this first when working on any FaceKom project. Provides rapid onboarding for AI agents.

What is FaceKom?

Enterprise identity verification (KYC/eKYC) platform by TechTeamer. Real-time face recognition, document verification, liveness detection for banking, telecom, government.

Internal codename: vuer across all services.

Architecture at a Glance

Customer Browser
       │ HTTPS
    Nginx (in front; see facekom-v2)
       │
  ┌────┴────┐
  │         │
vuer_css  vuer_oss ──── vuer_cv
(React)   (Node.js)     (Python/ML)
:10082-3  :10080-1      GPU inference
  │         │
  └────┬────┘
    RabbitMQ (RPC)
       │
  PostgreSQL / Redis

Service Quick Reference

Service	Tech	What it does	Key file
vuer_oss	Node.js, Sequelize, Express	Backend API, auth, business logic, DB	server/db/models.js (critical, 61 models)
vuer_css	React, Express, Socket.IO	Customer UI, queue management, real-time	server.js (entry)
vuer_cv	Python, ONNX, PyTorch	CV inference: 16 cv/*_engine modules; 10 app_*.py entrypoints (HTTP + WS + 8 model workers)	app_http.py (REST, 24 routes), app_websocket.py (WS); app_face.py/app_ocr.py are model workers
pdfservice	Node.js	PDF generation	-
esign_css/oss	Node.js	Electronic signatures	-

Critical Knowledge

vuer_oss Gotchas

• server/db/models.js is the single point of failure - 61 models, many files import it (408-line aggregator wires every association centrally)
• Mixed JS/TS: .js files require('.ts') with explicit extension
• No ts-node: Relies on Node experimental TS support
• Module syntax: ESM imports + CJS exports in same file
• Crash = fast loop: Supervisor restarts in 1-2s, fills logs quickly

vuer_css Gotchas

• Bilingual required: Every UI string needs EN + HU in locales/
• No direct DB: All data via RabbitMQ RPC to vuer_oss
• Per-page bundling: Separate CSS/JS bundles per page

vuer_cv Gotchas

• Git LFS required: git lfs pull for model weights
• GPU modes: INFERENCE_DEVICE_MODE = cpu/gpu/force_gpu
• Nginx generated: Runtime Jinja2 templates from scaling config

Communication Patterns

From → To	Protocol	Notes
vuer_css ↔ vuer_oss	RabbitMQ RPC	32 RPC servers + 18 clients + 16 queue servers (vuer_oss); 31 clients + 17 queues (vuer_css)
vuer_oss → vuer_cv	HTTP/WebSocket	CV inference requests
Browser ↔ vuer_css	Socket.IO + WebRTC	Real-time video, chat
All services	Supervisor	Process management

Development Environment (levander)

Build/test host CHANGED (2026-07-01) — ssh Facekom is DEAD

The on-prem box (ssh Facekom → ProxyJump FKJumpBox → root@lederera-447-fk-hardver) is decommissioned (offline since ~2026-06-27). All native builds, tests and deploys now run on the fk-dev Tailscale VM — command ssh ops@fk-dev.taild4189d.ts.net (100.91.108.61). Never use ssh Facekom again. Full detail: dev-build-host. Still build native on the remote host, NOT emulated on the Mac (qemu SIGSEGV / overlay-IO failures) — only the host changed. ssh gotcha: the user’s shell aliases ssh/scp to a _kaku_wrapped_ssh function that is not loaded non-interactively → use command ssh / command scp.

Item	Location
Build/test host	fk-dev GCP VM on tailnet taild4189d.ts.net (100.91.108.61)
SSH	command ssh ops@fk-dev.taild4189d.ts.net (Tailscale SSH, no keypair)
Old host	ssh Facekom / lederera-447-fk-hardver — decommissioned 2026-06-27
Remote workspace	/workspace/vuer_*/ (bind-mounted into each container)
Service URLs	Tailscale MagicDNS, e.g. operator UI https://oss-fk-dev.taild4189d.ts.net
Containers	Docker (vuer_docker compose on fk-dev) + per-service Tailscale sidecars
Container registry	harbor.techteamer.com
Issue tracker	JIRA: FKITDEV-XXXX
Branches	feature/FKITDEV-XXXX
GitHub org	TechTeamer
Obsidian docs	/Users/levander/levandor_obsidian/projects/facekom/

Tech Stack Summary

Layer	Technologies
Backend	Node.js >= 22.18.0, Express, Sequelize (TechTeamer fork), Passport.js
Frontend	React 18, Browserify/esbuild, Stylus, i18n (EN/HU)
ML/CV	Python, ONNX Runtime, PyTorch, Detectron2, OpenCV
Databases	PostgreSQL (primary), MySQL, MSSQL, Oracle
Messaging	RabbitMQ (@techteamer/mq)
Caching	Redis
Video	Janus WebRTC Gateway, Socket.IO
Auth	Passport (Local, SAML, AD, FIDO2, TOTP), JWT/JWE
Infra	Nginx, Supervisor, Docker Compose, Tailscale

Coding Conventions (Shared Across All Services)

Rule	Detail
Module system	CommonJS (require/module.exports)
Style	StandardJS (ESLint), single quotes, NO semicolons, 2-space indent
Braces	Always required (curly: error), 1TBS style
Console	no-console: error in production code (allowed in engines/, bin/, db/)
File naming	kebab-case for files, PascalCase for classes, camelCase for variables
Endpoints	name.endpoint.js pattern
Services	NameService.js pattern
DI	Service container pattern (server/service_container.js)
Hooks	ServiceBus emitter for lifecycle events and customization
Config	getconfig with AJV JSON Schema validation
Config access	config.get('path.to.key', defaultValue), config.has('key')
Linting	ESLint v9 (flat config), yarn lint with --max-warnings 0
Testing	Jest v30 (unit), Playwright v1.56 (e2e, vuer_oss only)
Package manager	Yarn
Build	esbuild (internal JS), Browserify (externals), Stylus → PostCSS → CleanCSS

Service Container (DI Namespaces)

The central DI object serviceContainer is accessible everywhere within a process:

Namespace	Purpose
serviceContainer.emitter	ServiceBus event emitter (hooks, overrides, lifecycle)
serviceContainer.logger	Log4js structured logging
serviceContainer.service	Business logic services
serviceContainer.rpcServer	RabbitMQ RPC servers
serviceContainer.rpcClient	RabbitMQ RPC clients
serviceContainer.queueServer	Queue message consumers
serviceContainer.queueClient	Queue message publishers
serviceContainer.publisher	Pub/sub publishers (broadcast to all processes)
serviceContainer.subscriber	Pub/sub subscribers
serviceContainer.dbModels	Sequelize model instances (vuer_oss only)
serviceContainer.customizations	Customer-specific extensions (same structure as above)

Common Commands

# vuer_oss
yarn dev                    # Dev mode with live reload
yarn build                  # Production build (esbuild)
yarn test:unit              # Jest unit tests
yarn test:e2e               # Playwright E2E (WARNING: can erase DB!)
 
# vuer_css
yarn dev                    # Dev mode
yarn build                  # Production build
yarn test:unit              # Jest unit tests
 
# vuer_cv (via Docker)
docker-compose -f vuer-cv-dev.yml up -d
./requirements/compile.sh   # Compile Python deps
./requirements/install.sh   # Install Python deps
git lfs pull                # Download model weights
 
# Infrastructure
supervisorctl status        # Check process status on remote
supervisorctl restart vuer  # Restart a process

Deeper Reading

• facekom-v2 knowledge base - Authoritative, source-verified successor to this quick-reference (built 2026-05-30; every claim cited to repo/path:LINE). When facts conflict, trust facekom-v2. Location: /Users/levander/levandor_obsidian/projects/facekom-v2/
• FaceKom - Full ecosystem overview
• vuer_oss - Backend deep dive (architecture, DB, auth, testing)
• vuer_css - Frontend deep dive (pages, build, patterns)
• vuer_cv - CV service deep dive (models, GPU config, scaling)
• dev-build-host - where to build/test (fk-dev Tailscale VM; old ssh Facekom box is dead)
• infrastructure - DNS, networking, containers
• debugging-log - Past bugs and their resolutions