Levandor

Conventions & Glossary

11 min read

Conventions & Glossary

Cross-repo coding, branch-naming, and file-naming conventions for FaceKom, plus a glossary of internal codenames. Every item is cited to source actually opened. Siblings: INDEX, architecture-overview, customization-architecture, customization-branch-catalog, vuer_oss, vuer_css.

Scope of evidence

Verified against the working trees and remote refs of vuer_oss, vuer_css, esign_oss, esign_css, portal_css, vuer_docker, vuer-release under /Users/levander/coding/facekom/, plus clones under /Users/levander/coding/facekom-v2-clones/ (vuer_cv, vuer_emrtd). Branch-naming is verified from real remote branch names (git for-each-ref refs/remotes/origin/), not from documentation.

1. Coding conventions

1.1 Linting baseline — StandardJS + extensions

All JS Node repos share a near-identical ESLint flat config (eslint.config.mjs); portal_css still uses legacy .eslintrc.json. Common base across every repo:

  • Base style: standard (StandardJS) — extended via compat.extends('standard', ...) (vuer_oss/eslint.config.mjs, vuer_css/eslint.config.mjs, esign_oss/eslint.config.mjs, esign_css/eslint.config.mjs) and "extends": ["standard", ...] (portal_css/.eslintrc.json:3). StandardJS implies: no semicolons, single quotes, 2-space indent, no unused vars, space-before-function-paren. Confirmed in real code — vuer_oss/server/service/UserService.js:1-14 has no semicolons, single-quoted strings, 2-space indent.
  • Plus plugin:n/recommended (Node plugin) and plugin:jest-formatting/strict (vuer_oss/eslint.config.mjs). portal_css instead uses plugin:node/recommended + plugin:react/recommended (React app, portal_css/.eslintrc.json:3).
  • Shared explicit rule overrides (identical block in vuer_oss, vuer_css, esign_oss, esign_css, portal_css):
    • curly: ['error', 'all']
    • 'brace-style': ['error', '1tbs', { allowSingleLine: false }] — One True Brace Style, no single-line blocks
    • 'guard-for-in': 'error', radix: 'error', 'no-empty-function': 'error'
    • 'no-console': 'error' (with per-area relaxations; browser/jquery contexts allow warn/error/info/time/timeEnd — vuer_oss/eslint.config.mjs)
    • 'no-debugger': 'error'
    • 'no-shadow': 'warn' (but 'error' in portal_css/.eslintrc.json)
  • ECMAScript level: 2020 (ecmaVersion: 2020 in every config). sourceType differs: vuer_oss = 'script'; vuer_css/esign_oss/esign_css = 'module' (eslint.config.mjs of each).
  • TypeScript: vuer_oss and vuer_css load @typescript-eslint/parser (tsParser); vuer_oss additionally enables @typescript-eslint plugin with '@typescript-eslint/no-require-imports': 'off' (vuer_oss/eslint.config.mjs). So the codebase is JS-first CommonJS with some TS allowed.
  • Ignored paths (lint): web/, client/libs/, client/polyfills/, logs/ (all repos’ ignores array; portal_css/.eslintignore lists /web/, /logs/, node_modules/).

Custom global vuer

ESLint registers a project-specific readonly global vuer in the Jest test context, alongside context, jestPuppeteer (vuer_oss/eslint.config.mjs, same in vuer_css/esign_oss/esign_css). Browser-context globals declared: bootbox, echarts, pdfjsLib, plus jQuery.

1.2 Lint / test invocation

From package.json scripts:

  • Lint (CI-grade, zero tolerance): lint = eslint . --max-warnings 0 --ignore-pattern "test/*" (identical in vuer_oss, vuer_css, esign_oss, esign_css). lint:fix = eslint . --fix && eslint --max-warnings 0 .
  • esign_css aliases test to a lint run: test = eslint . --quiet --ignore-pattern "test/*" (esign_css/package.json). portal_css test = npm run lint --silent (portal_css/package.json).
  • Unit tests via Jest: vuer_oss/vuer_css use jest --config ./test/jest.config.js --runInBand --forceExit; test:unit = yarn jest unit/* (vuer_css/package.json).
  • E2E via Playwright (vuer_oss/README.md: yarn test:e2e / yarn playwright test).
  • Build pipeline scripts (shared shape): build, style (bin/style/style.task), script (bin/script/script.task), watch (bin/watch/watch), dev = node bin/watch/watch --restart (vuer_oss/vuer_css), credits = node bin/credits > CREDITS.html.

1.3 Editor / formatting baseline

.editorconfig (vuer_oss/.editorconfig, root = true):

SettingValue
indent_stylespace
indent_size2
end_of_linelf
charsetutf-8
trim_trailing_whitespacetrue
insert_final_newlinetrue
max_line_length240
  • Package manager: Yarn (classic) — .yarnrc = --install.ignore-optional true (vuer_oss/.yarnrc); CI installs with yarn --frozen-lockfile (vuer_oss/.github/workflows/pull-request.yaml:34).
  • Browser support target: IE >= 11, Safari >= 11, Edge >= 16, Firefox ESR, last 2 years (vuer_oss/.browserslistrc).
  • Module system: CommonJS require/module.exports is dominant (vuer_oss/server/service/UserService.js:1-4). Enum-style constants use Object.freeze({...}) (UserService.js:6-11).
  • No code comments policy is NOT enforced in repo — JSDoc /** */ blocks exist in services (UserService.js:13). (The no-comments rule is the user’s personal global preference, not a FaceKom repo convention.)

1.4 CI conventions

  • PR CI runs on every pull request: jobs lint, test, audit, sonar, then a gating job needing [lint, test, audit, sonar] (vuer_oss/.github/workflows/pull-request.yaml:18,50,90,127,171-172). Audit uses yarn audit --groups dependencies + improved-yarn-audit (pull-request.yaml:111-114).
  • Branch CI (audit.yaml) triggers on push to devel and customization/* with Node 22 (vuer_css/.github/workflows/audit.yaml:4-7,19). Only vuer_css carries audit.yaml; the other code repos carry only pull-request.yaml.
  • SonarCloud is the static-analysis backend: sonar.host.url=https://sonarcloud.io, sonar.organization=techteamer, project keys like vuer-css (vuer_css/sonar-project.properties).
  • vuer-release uses a single autobuild.yml (tag-triggered Docker builds, vuer-release/.github/workflows/autobuild.yml, described in vuer-release/README.md).

1.5 Runtime / engines (per package.json engines.node)

RepoNode engineSource
vuer_oss>=22.18.0 (per repos/vuer_oss doc; engines block)vuer_oss/package.json
vuer_css>=22.0.0vuer_css/package.json
esign_oss>=22.13.0esign_oss/package.json
esign_css>=22.13.0esign_css/package.json
portal_css>=16.14.2 (older)portal_css/package.json

All code repos: private: true, author: TechTeamer, repo URLs github.com/TechTeamer/<name> (*/package.json).

2. Branch-naming conventions

Verified from actual remote branch names. Aggregated prefix counts (git for-each-ref refs/remotes/origin/ | grep -oE '^[a-z]+/' | sort | uniq -c). vuer_oss alone has 1062 remote branches.

2.1 Default / base branches

Repoorigin/HEAD (default)Source
vuer_oss, vuer_css, esign_oss, esign_css, portal_cssdevelgit symbolic-ref refs/remotes/origin/HEAD
vuer_docker, vuer-releasemastersame

Code repos branch off devel (the core product line); infrastructure/release repos (vuer_docker, vuer-release) use master. Some repos also still carry a legacy master ref (e.g. esign_oss, portal_css) but HEAD points at devel.

2.2 Verified prefix taxonomy (<type>/<slug>)

Top prefixes by frequency in vuer_oss (representative of all code repos):

PrefixCount (vuer_oss)Meaning / useExample (real)
feature/271New feature work, usually ticket-ledfeature/FKITDEV-1012-doc-scanner
customization/154Partner/client-specific code lines & fixescustomization/FKITDEV-3939-polgari-bank-branding
test/126Test branches(test/*)
fix/118Bug fixesfix/FKITDEV-300-instacash-mbh-rebranding-modifications
save/86Snapshots/backups of a partner state at a datesave/instacash-2021-09-21
update/84Re-sync of a customization onto a new base, datedupdate/customization/instacash-2026-05-27
mod/27Modificationsmod/FKITDEV-226-cig-muhammara
cr/22Change request (partner change request)cr/FKITDEV-3946-cofidis-pdf-password
feat/20Variant of feature/feat/FKITDEV-5794-instacash-remove-old-data
release/15Release branchesrelease/cib
improvement/12Improvements—
maintenance/10Maintenance / dependency upkeep, often datedmaintenance/customization/cofidis-2025-11
bugfix/8Synonym of fix/bugfix/FKITDEV-3597-name-regex
docs/6Documentationdocs/FKQA-227-libs-paaring-with-features
chore/4Choreschore/FKQA-263-semantic-release
upgrade/5Dependency upgradesupgrade/mq
bug/, change/, cleanup/, coverage/, refact/, development/, hotfix/, wip/, backup/, dependabot/1–4 eachLong tailchange/FKQA-141/update-phone-number-masking

Prefix discipline is loose. Real branches show typos (feautre/, featuer/, imporvement/) and overlapping synonyms (fix/≈bugfix/≈bug/; feature/≈feat/≈feautre/; refact/≈refactor; docs/≈doc/). Treat the prefix as a hint, not a contract. (vuer_oss aggregated prefix list.)

2.3 Customization / partner branch conventions (the load-bearing patterns)

These are the patterns the task highlights, all verified:

  • customization/<client> — the canonical long-lived partner branch. Real: customization/instacash, customization/raiffeisen, customization/cofidis, customization/sberbank, customization/cig, customization/bankmonitor, customization/demo, customization/equilor, customization/maliatec (esign_oss, esign_css branch lists); customization/cib, customization/dunatakarek, customization/takarek-mfszh, customization/unicredit-srb (portal_css).
  • update/customization/<client>-<date> — a periodic re-sync of a customization onto the latest base, date-stamped YYYY-MM-DD. Real: update/customization/instacash-2026-05-27, update/customization/cofidis-2025-02-18, update/customization/demo-2025-04-16, update/customization/raiffeisen-2024-07-11 (esign_oss); update/customization/instacash-2025-12-08 (esign_css). The vuer_oss working tree was checked out on update/customization/instacash-2026-05-27 (see vuer_oss).
  • customization/FKITDEV-####-<client>-<slug> — a ticketed change targeted at a partner. Real: customization/FKITDEV-3939-polgari-bank-branding, customization/FKITDEV-5605-granit-branding, customization/FKITDEV-5036-nusz-remove-old-audio-video-attachment (vuer_oss).
  • save/<client>-<date> and maintenance/customization/<client>-<date> — dated snapshots / maintenance lines. Real: save/instacash-2021-09-21, save/raiffeisen-2023-08-25 (esign_oss); maintenance/customization/cib-2025-11 (portal_css).
  • Partner-flavored feature branches embed the client in the slug: feature/FKITDEV-1449-localdev-<client> family (-bankmonitor, -demo, -instacash, -unicredit-srb, -otp, -mvm, -nusz, -szerencsejatek, …) (vuer_oss, portal_css).

See customization-architecture and customization-branch-catalog for the full partner roster.

2.4 feature/FKITDEV-#### and the ticket-prefix families

The task’s feature/FKITDEV-#### pattern is the dominant form. Aggregated across all 7 repos, ticket prefixes embedded in branch names (grep -oE '[A-Z]+-[0-9]+'):

Ticket prefixOccurrences (all repos)Notes
FKITDEV516Primary FaceKom IT-dev tracker
FKQA104QA tickets
FKDEV16older/dev
FKC12
TKMFSZHSSFK10Takarék MFSZH self-service partner
KHFK10K&H bank
DAP10
UNISRBFK5UniCredit Serbia
QTSPDEV/QTSP6Qualified Trust Service Provider work
ISSFK, RFK, BBFK, DTKFK, FKVIDEO, FKCV, FKDEVOPS, BUGMVM, COFIDISFACEKOM, CRVKTA, BMFKSAAS, …1–5 eachPer-partner / per-area trackers

Tickets are YouTrack, not Jira.

PR templates ask for “YouTrack ticket(s)” (vuer_css/PULL_REQUEST_TEMPLATE.md, esign_oss/PULL_REQUEST_TEMPLATE.md, portal_css/pull_request_template.md) and the changelog links to https://youtrack.techteamer.com/issue/FKITDEV-#### (vuer_oss/changelog.md). So FKITDEV-#### etc. are YouTrack issue IDs. (The task brief says “JIRA-like”; the actual tracker is YouTrack.)

2.5 Slug separator: hyphen vs slash after the ticket

Both FKITDEV-####-<slug> (hyphen) and FKITDEV-####/<slug> (slash) occur. Real: FKITDEV-2999/update-webserver-report-directive vs FKITDEV-1299-import-export-reporting (both vuer_oss). No single enforced separator.

2.6 PR template convention

Every PR uses the same template body — sections Summary, References → YouTrack ticket(s) (default no ticket linked), Related PR(s) (default nothing) (vuer_css/PULL_REQUEST_TEMPLATE.md, identical in esign_oss, portal_css/pull_request_template.md).

3. File-naming patterns

Counts below are from the live vuer_oss checkout — which is on the customization/instacash branch, not devel — via recursive find, excluding node_modules/, .worktrees/, and .claude/ (the latter two hold detached worktree copies that would otherwise multiply every count). Re-verified 2026-05-30.

These are working-tree (instacash) figures — the devel base has fewer files

The numbers below count the checked-out customization/instacash tree. The devel base carries fewer partner files. Verified devel deltas (git ls-tree -r origin/devel): *Service.js = 129 (not 136), *.flow.handler.js = 14 (not 33 — the 14 core flows, before instacash adds its ic-* handlers). The naming patterns are branch-independent; only the totals differ by the customization overlay.

3.1 *.endpoint.js — HTTP route / API handlers

86 files (recursive, excluding node_modules/, .worktrees/, .claude/). Live under server/web/routes/ (75) and server/web/api/ (8 = 4 admin/ + 4 common/), plus customization/server/web/routes/ (3). 75 + 8 + 3 = 86.

  • Route pages: server/web/routes/homepage.endpoint.js, waiting-room.endpoint.js, we-are-closed.endpoint.js (vuer_css/server/web/routes/).
  • API endpoints (kebab-case, often self-service-*): server/web/api/self-service-start.endpoint.js, self-service-attachment.endpoint.js, css-ping-waiting-room.endpoint.js, kioskPing.endpoint.js (vuer_css/server/web/api/).

3.2 *Service.js — service-container services (PascalCase)

136 files (recursive, excluding node_modules/, .worktrees/, .claude/). 112 under server/ — of which 87 sit directly in server/service/ and 17 more in its sub-namespaces (CryptoServices/ 6, ArchiveServices/ 4, ReportServices/ 3, IntegrityCheckServices/ 2, plus 8 scattered elsewhere under server/: sms/, room-inspector/, queue/, ocr/, flow/, e-mail/, db/, cv/) — plus customization/server/service/ (22) and 2 under client/. 112 + 22 + 2 = 136. Each is a class XxxService registered into the giant service container (see vuer_oss §service_container).

  • Examples: server/service/UserService.js, VuerCVService.js, SelfServiceRoomService.js, TrustedTimestampService.js, MediaFileService.js, CertService.js, VideoChatService.js (vuer_oss/server/service/).

3.3 *.flow.handler.js — Self-Service flow handlers

33 files (recursive, excluding node_modules/, .worktrees/, .claude/), all under customization/flow/<flow-name>/<flow-name>.flow.handler.js. customization/flow/ has 34 direct subdirectories; 33 of them hold exactly one .flow.handler.js (one handler per flow directory), and one — statProvider/ — holds none. So 34 flow dirs / 33 handlers (vuer_oss/customization/flow/).

  • Core flow families: self-service-phase-1/, self-service-phase-2/, self-service-v2-phase-1/, self-service-v2-phase-2/, online-verification-phase-1/, online-verification-phase-2/, automated-test-1..6/, esign-registration/, customer-data-change-test/.
  • ic- prefix = instacash partner flows: ic-customer-verification-1, ic-loan-payment, ic-offer-handling, ic-self-service-v2-phase-1, ic-contract, ic-mfl-verification-1..4, etc. (mapping inferred from co-located customization/flow/ic-* next to the many instacash customization branches; the ic- flows live in the instacash customization tree).
  • A separate *.flow.js exists for the socket event layer: server/socket/events/videochat.flow.js (1 file). Translations for flows: customization/flow/flow.trans.js, base.flow.trans.js.

3.4 Other recurring patterns

PatternCountLocation / meaningSource
*.trans.js400Translation bundles (i18n), e.g. customization/sms/messageTypes.trans.js, customization/ocr/documents.trans.jsvuer_oss find
*.schema.json79 (≈)AJV config schemas under docs/config/schemas/vuer_oss/docs.json, find
*Data.js—Customization data classes, e.g. customization/user/UserData, customization/portal/PortalData.trans.jsUserService.js:4

Case conventions

PascalCase for classes/services (UserService.js, *Data.js). kebab-case for endpoints, flows, and route files (self-service-start.endpoint.js, self-service-v2-phase-1.flow.handler.js). Compound-suffix files use dotted tags (.endpoint.js, .flow.handler.js, .trans.js, .schema.json).

4. Glossary

TermDefinitionEvidence
vuerFaceKom’s internal codename for the product/repos. Used as repo prefixes (vuer_oss, vuer_css, vuer_cv, vuer_emrtd, vuer_build, vuer_docker, vuer-release), Docker build var VUER_TAG, and a reserved ESLint global vuer.Repo names; vuer_build/README.md (VUER_TAG, -b microsec-1.9.11.12); vuer_oss/eslint.config.mjs (vuer: 'readonly')
OSS = Operator Side ServerThe back-office / operator-side server: owns the PostgreSQL DB, crypto/keys, RPC business logic, recording pipeline.esign_oss/README.md:4 “FaceKom eSign operator side server”; esign_oss/package.json:4; vuer_oss
CSS = Client Side ServerThe customer-facing Express + Socket.IO server a browser/kiosk hits (homepage → waiting room → videochat). Talks to OSS over RabbitMQ.vuer_css/README.md:1 “Facekom Client Side Server (CSS)”; esign_css/README.md:4 “customer side server”
portal_cssA trimmed CSS variant: a customer portal (registration, JWT/credential login, password recovery, SCA) that redirects to CSS. Keeps “the core functionality from CSS”.portal_css/README.md (“Available features”)
CV = Computer Visionvuer_cv — the computer-vision service (face detection/comparison, liveness, hologram, OCR support). Python service (requirements/*.in, Git-LFS model weights). Orchestrated from OSS via VuerCVService.js.vuer_cv/Readme.md (Python, Git LFS weights); vuer_oss/server/service/VuerCVService.js
eMRTDelectronic Machine Readable Travel Document (ICAO 9303 ePassport/eID chip). vuer_emrtd reads passport/ID chip data groups (e.g. Hungarian DG13). Java service.vuer_emrtd/README.md:1 “FaceKom eMRTD processor”; refs ICAO DOC 9303-10
eSignFaceKom’s electronic-signature product (esign_oss + esign_css), separate from the core video-ID product. PAdES/qualified-signature features.esign_oss/README.md “FaceKom eSign operator side server”; esign_css/PULL_REQUEST_TEMPLATE.md; branch feature/pades (esign_oss)
Self-Service V2A product flow, not a customization branch. Implemented as flow-handler directories self-service-v2-phase-1/ & -phase-2/ (and ic-self-service-v2-phase-1 for instacash).vuer_oss/customization/flow/self-service-v2-phase-1/self-service-v2-phase-1.flow.handler.js
QTSPQualified Trust Service Provider (eIDAS) — appears as a ticket-prefix family (QTSP-1664, QTSPDEV-*) for trust-service work (timestamps, certs, trust lists).branch QTSP-1664 (vuer_oss); related repos timestamp_service, trust_list_proxy
JanusThe WebRTC media/gateway server used for video calls and recording (consumed by the OSS conversion pipeline).repos janus-api, janus-sdk (facekom-v2-clones/); janus-api
FaceKomThe product/company brand (TechTeamer’s video-identification / KYC + video-banking platform). Repos are private, owner TechTeamer.*/package.json (author: TechTeamer); vuer_oss/README.md “FaceKom OSS”
YouTrackThe issue tracker; ticket IDs FKITDEV-####, FKQA-####, etc.PR templates “YouTrack ticket(s)”; vuer_oss/changelog.md links youtrack.techteamer.com
vuer_build / vuer-releaseBuild & release tooling. vuer_build: Docker build env that packages partner source bundles (Hungarian README). vuer-release: tag-triggered Docker image build via vuer-release-cli + release.json descriptors.vuer_build/README.md; vuer-release/README.md
vuer_dockerThe developer environment: docker-compose stacks for the whole platform (oss, css, esign, cv, janus, postgres, rabbitmq, …). Default branch master; partner-named branches (e.g. kh, mbh, cofidis).vuer_docker/README.md; branch list
ic-Filename/flow prefix for instacash partner customizations (e.g. ic-loan-payment.flow.handler.js).vuer_oss/customization/flow/ic-*; many instacash branches

Clarifications vs the task brief

  • “Self-Service V2 = product flow NOT a branch” is correct as a customization branch statement, but the slug self-service-v2 does appear inside ad-hoc feature//fix/ branch names (e.g. feature/web-self-service-v2, feature/self-service-v2-history, fix/uc-selfservice-v2 in vuer_oss). It is not a long-lived customization/<client> line.
  • The brief calls tickets “JIRA-like”; the actual tracker is YouTrack (see above).

Sources

Files / refs actually read:

  • ESLint configs: vuer_oss/eslint.config.mjs, vuer_css/eslint.config.mjs, esign_oss/eslint.config.mjs, esign_css/eslint.config.mjs, portal_css/.eslintrc.json, portal_css/.eslintignore
  • package.json (name/version/private/author/engines/scripts): vuer_oss, vuer_css, esign_oss, esign_css, portal_css
  • vuer_oss/.editorconfig, vuer_oss/.yarnrc, vuer_oss/.browserslistrc, vuer_oss/docs.json, vuer_oss/changelog.md (head)
  • vuer_oss/.github/workflows/pull-request.yaml, vuer_css/.github/workflows/audit.yaml; workflow listings for esign_oss, esign_css, portal_css, vuer_docker, vuer-release; vuer_css/sonar-project.properties
  • READMEs: vuer_oss/README.md, vuer_css/README.md, esign_oss/README.md, esign_css/README.md, portal_css/README.md, vuer_build/README.md, vuer_docker/README.md, vuer-release/README.md; vuer_cv/Readme.md, vuer_emrtd/README.md
  • PR templates: vuer_css/PULL_REQUEST_TEMPLATE.md, esign_oss/PULL_REQUEST_TEMPLATE.md, portal_css/pull_request_template.md
  • vuer_oss/docs/developer-documentation.md (head)
  • Code samples: vuer_oss/server/service/UserService.js
  • Branch names: git for-each-ref refs/remotes/origin/ + git symbolic-ref refs/remotes/origin/HEAD for vuer_oss, vuer_css, esign_oss, esign_css, portal_css, vuer_docker, vuer-release
  • File patterns: find over vuer_oss (and vuer_css) for *.endpoint.js, *Service.js, *.flow.handler.js, *.flow.js, *.trans.js, *.schema.json; flow dir listing vuer_oss/customization/flow/
  • Orientation only (claims re-verified independently): /Users/levander/levandor_obsidian/projects/facekom-v2/repos/vuer_oss.md

Graph View

Backlinks