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 (:30080/:20080)
       │
  ┌────┴────┐
  │         │
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.ts (critical)
vuer_css	React, Express, Socket.IO	Customer UI, queue management, real-time	server.js (entry)
vuer_cv	Python, ONNX, PyTorch	16 ML models, 10 Supervisor processes	app_face.py, app_ocr.py
pdfservice	Node.js	PDF generation	-
esign_css/oss	Node.js	Electronic signatures	-

Critical Knowledge

vuer_oss Gotchas

• models.ts is the single point of failure - 70+ entities, 35+ files import it
• 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	15+ RPC servers, 20+ RPC clients
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)

Item	Location
Remote server	Ubuntu 22.04.5 LTS via SSH + Tailscale
SSH alias	ssh Facekom (ProxyJump through FKJumpBox → root@lederera-447-fk-hardver)
Remote workspace	/workspace/vuer_*/
DNS	dnsmasq: *.facekomdev.net → Tailscale 100.103.48.49
Containers	Podman 5.7.1 (not Docker)
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	ESLint standard, single quotes, 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 - 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)
• infrastructure - DNS, networking, containers
• debugging-log - Past bugs and their resolutions