FaceKom’s operator/admin backend. Handles video identification sessions, document management, workflow engine, face recognition, reporting, archive/export, and all database operations. The largest and most complex service in the FaceKom ecosystem.
vuer_oss runs as 7 separate Supervisor-managed Node.js processes, all sharing the same codebase but with different entry points. All inter-service communication with vuer_css goes through RabbitMQ. Communication with vuer_cv happens over HTTP/WebSocket.
graph TB
subgraph "vuer_oss Processes"
MAIN["vuer_oss<br/>server.js<br/>:10080/:10081"]
CRON["vuer_cron<br/>cron.js"]
BG["vuer_background<br/>background.js"]
CONV["vuer_oss_convert<br/>convert.js"]
MEDIA["vuer_media<br/>media.js<br/>:10079"]
STOR["vuer_oss_storage<br/>storage.js"]
ILOG["vuer_integration_log<br/>integrationLog.js"]
end
subgraph "External"
RMQ["RabbitMQ"]
PG["PostgreSQL"]
REDIS["Redis (HA)"]
CSS["[[vuer_css]]"]
CV["[[vuer_cv]]"]
JANUS["Janus WebRTC"]
end
MAIN --> RMQ
MAIN --> PG
MAIN --> REDIS
MAIN --> CV
MAIN --> JANUS
RMQ <--> CSS
CRON --> RMQ
CRON --> PG
BG --> RMQ
BG --> PG
CONV --> RMQ
MEDIA --> PG
STOR --> RMQ
ILOG --> RMQ
ILOG --> PG
Entry Points & Boot Sequence
Process
Entry
Port
Purpose
vuer_oss
server.js
:10081 (HTTP), :10080 (Socket.IO)
Main web + socket server
vuer_cron
cron.js
-
Scheduled tasks (19+ possible cron jobs)
vuer_background
background.js
-
Long-running jobs (reports, exports, OCR)
vuer_oss_convert
convert.js
-
Video/audio transcoding (FFmpeg)
vuer_media
media.js
:10079
Authenticated media streaming
vuer_oss_storage
storage.js
-
File archival between storage engines
vuer_integration_log
integrationLog.js
-
API integration audit logging with encryption
All processes managed by Supervisor.
Common Boot Sequence
Every process follows the same pattern:
flowchart TD
A["process-settings()"] --> B["process-listeners()"]
B --> C["Load config"]
C --> D["setupServices() — subset per process"]
D --> E["Connect DB"]
E --> F["Connect Redis (optional, HA)"]
F --> G["Connect RabbitMQ"]
G --> H["initServices()"]
H --> I["setupQueue() — consumers/producers"]
I --> J["customization hooks"]
J --> K["Start — web/cron/queue"]
K --> L["Emit system.start"]
server.js (Main Server)
Instantiates ~80+ services into serviceContainer.service.*
Starts both Express web server and Socket.IO server
Emits system.start event at the very end, triggering audit log
Subset of services — no socket, no web server, no transport pool
RPC server for reports, archive, recognition, room export
cron.js
Creates CronJob instances, stores in serviceContainer.cron, starts all
19+ possible cron jobs based on config
convert.js
Minimal services — crypto, media file, hash, trusted timestamp, SFTP
Consumes from queue-convert
Pre-check: runs convert_check.js to verify FFmpeg availability
media.js
Full WebServer instance but only with media routes, no Socket.IO
Port 10079
storage.js
Both server and client for queue-storage
integrationLog.js
Creates daily encryption keys, has rate limiting, dumps on exit
Bootstrap & Initialization
process-settings.js
Sets process.env.TZ = 'Etc/UTC'
Security: Global TLS Bypass
If config.settings.allowSelfSignedCerts is true, sets NODE_TLS_REJECT_UNAUTHORIZED = '0' — disables all TLS certificate verification globally. See security-audit.
On RabbitMQ connection close, calls process.exit(2) immediately — no graceful shutdown.
connection/redis.js
Only connects if HARedis.config is set
Used for HA waiting room
Reconnect strategy: max 10 retries at 500ms intervals, then gives up
Service Container & Dependency Injection
File: server/service_container.js
The service container is a singleton module that serves as:
A DI container (serviceContainer.service.*)
An event bus (serviceContainer.emitter — a WildEmitter subclass called ServiceBus)
A registry for all major subsystems (db, dbModels, queue, io, transportPool, etc.)
God Object Pattern
The service container holds everything — 80+ services, DB, queue, socket, transport, etc. This is both the strength (easy to access anything) and the weakness (tight coupling, hard to test, hard to reason about lifecycle). See tech-debt.
ServiceBus
Extends WildEmitter with:
Method
Behavior
addHook(tag, handler)
Register hook handler
callHooks(tag, ...params)
Promise.all execution of all handlers for tag
callOnlyHook(tag, ...params)
Calls first registered hook only
registerOverride(name, fn)
Single-function override
callOverride(name, ...args, default)
Call override or default
Used for extensibility via customization/ directory.
Key Properties on serviceContainer
Property
Content
logger, auditLog, diagnostic
Infrastructure
db, dbModels, dbHelpers
Database layer
HARedisClient
Redis (HA waiting room)
queue, queueConnectionPool
RabbitMQ
rpcServer.*, rpcClient.*
RPC pattern
queueServer.*, queueClient.*
Queue pattern
publisher.*, subscriber.*
Pub/Sub pattern
transportPool, roomTransportStorage
Transport layer
io
Socket.IO server
webServer, webServerAuth, sessionStore
Web layer
service.*
~80+ business services
cron.*
Cron jobs (cron.js only)
Configuration System
File: config.js
Uses getconfig library (reads from config/*.json based on NODE_ENV)
Optional Spring Cloud Config Server integration with retry
Custom config.get(path, default) and config.has(path) methods
config.getSecureConfig(): Masks sensitive fields defined in security.sensitiveConfigFields
config.traceConfig(): Flattens entire config to sorted string list for debugging
Feature
Details
Dev mode
Auto-generates hostnames from /etc/hostname
Travis CI mode
Hardcodes RabbitMQ to localhost
Version
Appends build number from .env file
CORS
Secure-by-default — replaces * with actual hostname
LDAP/AD auth; multiple AD configs; maps AD groups to roles; falls through on failure
SamlStrategy
SAML 2.0 SSO via @node-saml/passport-saml; extracts email, username, names from SAML attributes
WebAuthnStrategy
FIDO2/WebAuthn via passport-fido2-webauthn; challenge store in session; supports credential registration
TotpStrategy
Time-based OTP via passport-totp; paired with local auth as second factor
UniqueTokenStrategy
Custom token-based API auth: JWE (encrypted via JOSE keystore), JWT (signed), One-Time Login
Auth Flows
flowchart LR
A["Login Request"] --> B{"Auth Type?"}
B -->|Interactive| C["Local / AD / SAML"]
B -->|Token| D["JWE / JWT / OTL"]
C --> E{"2FA Required?"}
E -->|Yes| F["SMS / TOTP / WebAuthn"]
E -->|No| G["Session Created"]
F --> G
D --> G
Creates Socket.IO server with config-based options. Registers 13+ event modules on each connection. Supports recovered connections (socket.io v4 feature).
Event Modules
Module
Purpose
client.js
Client connection/disconnection handling
auth.js
Socket authentication via JWT token
acl.js
Access control for socket events
pagevisit.js
Page visit tracking
echotest.js
WebRTC echo test
ping.js
Latency measurement
videochat.js
Core video chat events
videochat.validation.js
Customer validation during video chat
videochat.customerDataChange.js
Live customer data editing
videochat.flow.js
Flow execution during video chat
videochat.presentation.js
Document presentation mode
headerinfo.js
Header information updates
webrtclog.js
WebRTC logging
cert.js
Certificate management
waitinglist.js
Waiting list management
flow.js
Flow management (optional, ACL-gated)
cronManager.js
Cron job management (optional, ACL-gated)
customerdata.js
Customer data changes (optional, ACL-gated)
RabbitMQ Queue System
Uses @techteamer/mq library with 4 messaging patterns. See rabbitmq-communication for full queue documentation.
EventEmitter throughout (TransportSession, VuerCVWebSocket, ServiceBus, Socket.IO)
Middleware Chain
Express middleware stack, Socket.IO event modules
Feature Flags
Extensive config.get() to conditionally enable services, routes, queues, cron jobs
Customization Layer
customization/ directory provides extension points for API routes, flow handlers, email templates, cron jobs, listeners, portal data, OCR documents
Project Structure
server/
web/ Express app, routes, middleware, API endpoints
socket/ Socket.io server and event handlers
queue/ RabbitMQ RPC servers/clients and queue handlers
service/ Business logic services (80+)
db/ Database models (65), relationships, helpers
model/ Sequelize model definitions
models.js Model instantiation and relationships
flow/ Workflow execution engine (tasks, conditions, branching)
cron/ Scheduled task definitions (19+)
convert/ Media conversion workers (FFmpeg)
e-mail/ Email service (Nodemailer + MJML templates)
sms/ SMS service
cv/ Computer vision (face detection, MRZ recognition)
ocr/ OCR recognition engines and processing
faceRecognition/ Face recognition engine and hooks
webrtc/ WebRTC/Janus gateway integration
transport/ Bidirectional oss<->css transport layer
portal/ Portal data management and data matching
partner/ Partner integration logic
listeners/ Event listeners
backgroundProcess/ Background process handlers
room-inspector/ Room state inspection
bootstrap/ App initialization (DB, Redis, RabbitMQ, process settings)
acl/ Access control list
errors/ Custom error classes
logger/ Log4js structured logging
util/ Utility modules
service_container.js DI container (God Object)
auth.js Passport.js strategies (local, SAML, AD, FIDO2, TOTP)
auditlog.js Event-driven audit logging (50+ events)
diagnostic.js Real-time health monitoring
gcm.js AES-256-GCM encryption implementation
client/
engine/ Custom MVC framework (View, Controller, Service, Metadata)
features/ Feature modules (auth, videochat, socket, flow, etc.)
ui/ UI templates, components, styles (Stylus)
elements/ 60+ reusable UI elements
pages/ 50+ page types (admin, reports, appointments, video)
layouts/ Layout templates
styles/ Stylus CSS
customization/ Extension hooks (white-label)
api/ API extensions
flow/ 14 predefined flows (self-service, online verification, esign)
email/ Email template overrides
cron/ Cron job extensions
listeners/ Event listener hooks
ocr/ Country-specific OCR (HU, RS, SLO IDs/passports/licenses)
engines/ Specialized engines
worker/ Worker pool executors
translator/ Translation/i18n engine
storage/ Storage drivers (local, S3)
build/ Build utilities
twig/ Template engine
db/ Database migrations
migrate/ Sequential migration files (timestamp-named)
beforeMigrate/ Pre-migration hooks
workers/ Background workers (bcrypt.js password hashing)
web/ Compiled static assets (DO NOT edit)
config/ Environment configs (dev.json, docker.json, local.json, roles.json)
test/ Test suites (unit, e2e, integration, regression)
docs/ Documentation and config schemas (40+ feature docs)
bin/ CLI utilities and build scripts
Testing
yarn test:unit # Jest unit testsyarn test:e2e # Playwright E2E tests (WARNING: can erase DB!)yarn jest test/tests/unit/ # Specific directoryyarn jest sometest.test.js # Single file
Jest: V8 coverage, 30s timeout, no transform
Playwright: Desktop Chrome, single worker, 1720x1080, camera/mic permissions
E2E requires: both vuer_oss AND vuer_css built and running
Test configs: test/testconfigs/test-config-ci.json (OSS), test-css-config.json (CSS)
Shared fixtures: /workspace/test_resources
Development
yarn dev # Live reload with automatic file rebuildingyarn build # Production build (esbuild)
Known Gotchas
Gotcha
Details
Mixed JS/TS
JavaScript files require() TypeScript files with explicit .ts extension
No TS runtime
No ts-node/tsx; relies on Node.js --experimental-transform-types or similar
models.ts is critical
server/db/models.ts imported by 35+ files; single point of failure
Mixed module syntax
ESM import + CJS module.exports in same file (models.ts)
Crash loop risk
Missing model files cause immediate crash; Supervisor rapidly restarts
Recent Debugging (March 2026)
Crash Loop - Missing Model Module (FKITDEV-7855)
Symptom: ERR_MODULE_NOT_FOUND for server/db/model/room, Supervisor cycling PIDs
Root cause: Missing callbackrequest model + .ts extension resolution issues
Fix: Added .ts extensions to require statements across 38 files
Lesson: models.ts is the critical hub; always verify module paths
Sequelize Import Error
CreationOptional TypeScript type used in runtime without transpilation
Part of broader TS/JS compatibility issue in the codebase