ODP Service API

Appearance

ODP Backend API — Sitemap ​

TLDR: Bản đồ treeview chi tiết của backend @odp/api (Fastify 5 + Knex, TypeScript ESM). Mỗi mục 1 title + 1 mô tả ngắn để định vị; chi tiết xem từng trang trong docs/api/.

Đường dẫn gốc: service/api/src. Bản tổng thể toàn platform: docs/sitemap.md.

Mỗi item kèm 🧩 ext: — extension dùng/hook được gì ở đó. Extension nhận ApiExtensionContext { services, emitter, database, getSchema, env, logger, validateAppAccess }; endpoint nhận thêm Fastify scoped instance. (Chi tiết: Extension Development.)

Ranh giới + được/không được chạm gì khi viết extension: Extension Guardrails.

1. Request pipeline (thứ tự middleware) ​

  • extractToken — lấy token từ header/cookie/query
    • header — Authorization: Bearer
    • cookie / query — fallback (access_token)
  • rateLimiterGlobal → rateLimiterIP — giới hạn tần suất
    • global — tổng tải toàn hệ thống
    • per-IP — theo địa chỉ IP
  • authenticate — xác thực → gắn accountability · 🧩 ext: trong endpoint đọc request.accountability
    • verify JWT — kiểm chữ ký + hạn
    • session cache — tra session, correlation id
    • anonymous — accountability mặc định khi không token
  • loadSchema — nạp SchemaOverview vào request · 🧩 ext: dùng context.getSchema()
  • sanitizeQuery — chuẩn hoá filter/fields/sort/limit, chặn quá sâu
  • collectionExists — chặn collection hệ thống (odp_*) khỏi /items
  • handler — route logic (gọi service) · 🧩 ext: endpoint = nơi extension mount route
  • cacheResponse (onSend) — cache HTTP response (opt-in)
  • error-handler — chuẩn hoá lỗi (error hierarchy) · 🧩 ext: throw từ utils/errors

2. Core runtime ​

  • Server bootstrap (server.ts, index.ts) · 🧩 ext: hook server.start / server.stop (init)
    • phase 1 — scanAndLoadHooks (đăng ký hook trước khi có server)
    • phase 2 — createServer + plugins + middleware + routes + loadEndpoints
    • phase 3 — initializeApp (hot-reload watcher)
  • Emitter (emitter.ts) · 🧩 ext: API hook chính — context.filter/action/init/schedule; phát event qua context.emitter.emitAction/emitFilter
    • filter — đồng bộ, transform payload (before)
    • action — fire-and-forget, song song (after)
    • init — tuần tự, await (server.start...)
    • matching — exact, items.*, *.items.create, *
  • Env (env.ts) — validate Zod, useEnv() · 🧩 ext: context.env
  • Logger (logger.ts) — pino child theo tên · 🧩 ext: context.logger
  • Cache (cache/)
    • response cache — HTTP response, opt-in CACHE_ENABLED
    • system cache — schema/permission
    • store — memory / redis
  • Schedules (schedules/) — cron đồng bộ đa node · 🧩 ext: context.schedule(cron, fn)

3. Data layer — CRUD & schema ​

  • Items service — CRUD nền tảng · 🧩 ext: services.ItemsService(coll,{knex,accountability,schema}); hook items.create/update/delete/read + <col>.items.* (dùng {emitEvents:false} chống loop)
    • createOne / createMany — tạo (batch suppress per-item event)
    • readByQuery / readOne / readMany — đọc qua AST + permission
    • updateOne / updateMany — sửa
    • deleteOne / deleteMany — xoá
    • verifyRowAccess — kiểm row-level trước mutation
    • MutationOptions — emitEvents, bypassLimits, skipCacheClear...
  • Query engine (database/ast/) · 🧩 ext: truy vấn qua ItemsService.readByQuery(query) (không gọi AST trực tiếp)
    • from-query — parse params → AST
    • filter-parser — filter (_eq/_in/_and/_or...) → SQL
    • sort-parser — sắp xếp đa field
    • aggregate — count/sum/avg/group
    • search — full-text ?search=
    • process-ast — chèn điều kiện permission (row-level)
    • inject-cases — CASE cho field-level
    • run — compile & thực thi
  • Collections / Fields / Relations — schema động · 🧩 ext: services.CollectionsService/FieldsService/RelationsService; hook collections.* / fields.*
    • collections — tạo/sửa/xoá collection + metadata
    • fields — kiểu, interface, special, validation
    • relations — M2O / O2M / M2M / M2A
  • Schema inspector (inspector.ts) — introspect tables → SchemaOverview + merge odp_collections/_fields/_relations · 🧩 ext: context.getSchema()
  • Database (database/) · 🧩 ext: context.database (Knex) cho query/bảng riêng của extension
    • dialects — postgres / mysql / sqlite
    • migrations — NNN-* tuần tự, advisory lock, tracked odp_migrations
    • connection — Knex singleton
  • Payload service — special field (hash/json/date), relational nested, dynamic vars, presets · 🧩 ext: services.PayloadService (nâng cao)

4. Content lifecycle ​

  • Versions · 🧩 ext: services.VersionsService; hook versions.submit
    • createDraft / createOne — tạo version nháp
    • submit — gửi duyệt (status pending, emit versions.submit)
    • promote — merge delta vào item chính (create-or-update, giữ relation)
    • updateStatus / compareWithMain — đổi trạng thái, so diff với base
  • Revisions — snapshot lịch sử mỗi mutation · 🧩 ext: services.RevisionsService
  • Activity — log create/update/delete/login/comment · 🧩 ext: services.ActivityService (tự sinh từ items event)
  • Comments — bình luận trên item · 🧩 ext: services.CommentsService
  • Import / Export — nhập/xuất dữ liệu · 🧩 ext: services.ImportExportService

5. Auth & Access ​

  • Auth (auth/) · 🧩 ext: services.AuthService (hiếm dùng trực tiếp)
    • drivers — local (argon2), oauth2, openid, saml
    • endpoints — login / refresh / logout / password request·reset / sso providers·verify / saml acs·verify
    • token — access/refresh JWT, verify
  • Sessions / Sub-tokens · 🧩 ext: services.SubTokenService; hook sub-tokens.create/revoke
    • sessions — phiên đăng nhập, revoke
    • sub-tokens — scoped API token (theo scope/role), create/revoke
  • Impersonation — impersonate / stop / list·delete sessions (có audit) · 🧩 ext: services.ImpersonationService
  • me — hồ sơ & thao tác user hiện tại · 🧩 ext: services.UsersService + request.accountability
  • Permissions engine (permissions/) · 🧩 ext: tự enforce khi gọi service kèm accountability
    • fetch-policies → fetch-permissions — lấy policy & permission user
    • validate-access — quyền read/create/update/delete
    • validate-field-access / fetch-allowed-fields — field-level
    • validate-filter-permissions — chặn leak qua filter quan hệ
    • validate-payload — kiểm payload theo rule (matchesFilter)
    • process-ast — inject điều kiện row-level vào query
    • replace-variables — $CURRENT_USER, $NOW...
    • apply-presets / system-context / cache-invalidation — preset, ngữ cảnh, invalidate
  • App permissions — quyền module/UI · 🧩 ext: khai báo qua package.json#odp-extension.permissions + enforce bằng context.validateAppAccess(...)
    • app-module-registry — đăng ký module + action
    • validate-app-access — kiểm quyền module/action
    • app-access-permissions / logs — gán quyền + nhật ký truy cập
  • Users / Roles / Policies · 🧩 ext: services.UsersService/RolesService/PoliciesService
    • users — CRUD + invite/accept, register, verify-email, tfa disable, sessions
    • roles / policies — vai trò & chính sách truy cập
  • Registration / Providers — registration-fields, auth-providers (cấu hình SSO), user-providers (liên kết) · 🧩 ext: services.ProviderSettingsService/UserProvidersService

6. Files & Storage ​

  • Files — metadata tệp, CRUD · 🧩 ext: services.FilesService
  • Assets — phục vụ & transform ảnh (resize/format/quality) · 🧩 ext: services.AssetsService
  • Storage (storage/) · 🧩 ext: thao tác tệp qua FilesService
    • local — filesystem
    • s3 — AWS S3
    • manager — khởi tạo driver theo cấu hình
  • TUS — upload resumable (chunk)
  • Folders / Storage-providers — cây thư mục + cấu hình provider · 🧩 ext: services.ProviderSettingsService / FilesService

7. Modules (modules/*) ​

  • Workflow — engine duyệt nhiều bước · 🧩 ext: không expose service; tích hợp qua event versions.submit/items.* (engine tự nghe) hoặc REST /workflows*
    • engine — startInstance, approveStep, rejectStep, delegateStep, commentStep, handleTimeout, escalateStep, advanceFromTrx, promoteVersion, completeInstance
    • listener — auto-start theo items.create/update, versions.submit (+ trigger_filter, merge delta)
    • scheduler — cron mỗi 2' quét timeout → escalate/auto-approve/auto-reject/notify
    • resolver — resolve assignee: role / user / field / creator / auto
    • services / validation / routes — CRUD definition/step/transition/instance/task
  • Notify — thông báo đa kênh · 🧩 ext: emit context.emitter.emitAction('notify.trigger', {...}); services.NotificationsService (in-app)
    • engine / send / worker — dựng nội dung & gửi qua queue
    • providers — email, inapp (ghi odp_notifications), mattermost
    • template-renderer — render template + layout với biến
    • services — templates / layouts / contents / settings / logs
    • listener / sync-settings — hook trigger & đồng bộ cấu hình
  • MCP — Model Context Protocol server
    • server / transport — JSON-RPC qua HTTP, gated admin + mcp/access, scope theo accountability
    • tools — items, collections, fields, relations, schema, files, users, versions, activity, workflow-(definitions/instances/steps/transitions/tasks)
    • prompts — prompt template cho client AI
  • Metrics — Prometheus (prom-client): request, DB, custom

8. Security (security/*) ​

  • SSRF (ssrf/)
    • safe-fetch — fetch có kiểm tra
    • dns-cache / ip-validator — resolve DNS + chặn IP private
  • Rate-limit (rate-limit/)
    • store — memory / redis
    • per-user / per-endpoint — chiến lược giới hạn
  • Audit (audit/) — hash chain chống sửa log + scheduler verify
  • Drift (drift/) — so cấu hình giữa node + baseline + scheduler
  • Events (events/) — log security event + correlation id (logger/service/types)

9. Platform services & API surface ​

  • Extensions system (extensions/) · 🧩 ext: chính cơ chế chạy extension (hook + endpoint + context)
    • Service registry (registry.ts) · 🧩 ext: context.registry.provide/consume/tryConsume/has — chia sẻ service giữa extension; provide ở init extensions.register
    • types — hook / endpoint / bundle
    • loading — 2 phase, hot-reload, nạp từ folder + npm package
    • context — services, env, database, emitter, logger, getSchema
  • GraphQL — endpoint GraphQL trên schema động · 🧩 ext: services.GraphQLService
  • Routes (routes/) — REST surface · 🧩 ext: thêm route mới qua endpoint (router.get/post/... trên Fastify scoped instance)
    • content — items, collections, fields, relations, schema, versions, revisions, activity, comments
    • access — auth, me, users, roles, policies, permissions, access, app-permissions, sub-tokens
    • files — files, assets, folders, tus, storage-providers
    • config — settings, presets, translations, shares, notifications, extension-settings, auth-providers
    • system — server, utils, system-items, graphql, websocket
  • System-items — route admin đọc collection hệ thống (odp_*)
  • WebSocket — realtime subscription (opt-in WEBSOCKETS_ENABLED), auth strict/handshake/public · 🧩 ext: services.WebSocketService
  • Settings / Presets / Translations / Shares / Notifications — cấu hình & tiện ích chung · 🧩 ext: services.SettingsService/PresetsService/TranslationsService/SharesService/NotificationsService

10. CLI (cli/) ​

  • odp <command> — quản trị/scaffold qua dòng lệnh · 🧩 ext: odp dev chạy server dev hot-reload; odp-extension create|build [--watch] scaffold/build extension
    • migrate / seed — DB lifecycle
    • scaffold — tạo module/extension

Phụ lục — System tables (odp_*) ​

Tiền tố odp_: collections, fields, relations, users, roles, policies, permissions, access, sessions, activity, revisions, versions, comments, settings, presets, extensions, notifications, translations, shares, folders, files, migrations, notify_*, workflow_*, app_permissions, app_access_logs, user_tokens, user_providers, extension_settings, security_events.

🧩 Extension nên thao tác qua service (đúng permission/event), chỉ dùng context.database trực tiếp cho bảng riêng hoặc đọc nội bộ.

ODP Internal API Documentation