Architecture
@nx/assetships no runtime of its own. Every diagram below depicts the asset components as mounted inside a host application (commerce, finance, or ledger).
1. System Context (C4 L1)
2. Container View (C4 L2)
3. Component View (C4 L3) — Internal Layering
| Layer | Responsibility |
|---|---|
| Routes | HTTP surface, declared in StaticAssetRoutes / BanksVNRoutes / CRUD factory |
| Controllers | Path validation, auth gate, header shaping, stream/JSON response |
BunS3Helper | Object put/get/stat/remove/list against S3/Minio (bound under APPLICATION_S3_STORAGE_HELPER) |
MetaLinkRepository | Drizzle CRUD over public.MetaLink |
| Components | Wire helper + controllers into the host on binding() |
4. State Machines Index
| Entity | States | Diagram |
|---|---|---|
| — | N/A — MetaLink has no status field / lifecycle | — |
N/A — asset entities are flat records.
MetaLinkrows are created on upload and hard-deleted on object delete; there is no state machine.
5. Runtime Scenarios
5.1 Upload object + record MetaLink
| Step | Detail |
|---|---|
| 2 | folderPath normalized + each segment checked with helper.isValidName; max depth 2 |
| 3 | Object name = crypto.randomUUID().slice(0,8); i18n.json keeps its literal name |
| 6 | MetaLink failure does not fail the upload — error captured into metaLinkError per file |
5.2 Stream / download object
| Step | Detail |
|---|---|
| 1 | /objects/... streams inline; /download/... adds Content-Disposition: attachment |
| 2 | Invalid path → 400; missing object surfaces as helper error |
| — | GET /objects/i18n + GET /download/i18n stream the i18n.json bundle from APP_ENV_S3_BUCKET |
5.3 Serve VN bank registry + logo
6. Crosscutting Concerns
| Concern | How asset handles it |
|---|---|
| AuthN | Inherited from host (JWT/Basic). Mutating asset routes + /meta-links require BASIC or JWT; read/download + banks-vn are public |
| AuthZ | AssetPermissions = MetaLink CRUD perms exist, but MetaLinkController currently sets authorize: { skip: true } on every route |
| i18n | Serves the i18n.json translation bundle from S3; VN bank labels are static JSON |
| Logging | Structured key-value via this.logger.for(...); upload/delete MetaLink failures logged, not thrown |
| Path safety | isValidPath/isValidName (depth ≤2); bank logo regex ^[A-Za-z0-9]+\.png$; x-content-type-options: nosniff on streams |
| Idempotency | None — upload generates a fresh UUID name each call |
| Soft-delete | N/A — object delete hard-removes the S3 object and deleteAlls matching MetaLink rows |
| IDs | Host's IdGenerator (asset issues none) |