Asset Service

The Asset Service is a Java/Spring Boot 3.2 application that provides a unified, type-agnostic registry for all data platform assets. It manages the full lifecycle of assets including versioning with bundle manifests, Git-style branching, granular permission control, governance-driven approval workflows, and cross-asset cloning.

Service Architecture

Property	Value
Language	Java 21
Framework	Spring Boot 3.2
Port	8093
Namespace	`matih-data-plane`
Database	PostgreSQL
Event bus	Kafka (`matih.asset.*` topics)
Cache	Redis

Component Layout

+------------------------------------------------------------------+
|                        Asset Service                              |
|                                                                   |
|  +-------------------+  +--------------------+  +---------------+ |
|  | REST Controllers  |  | Version Lifecycle  |  | Event Layer   | |
|  | - AssetCtrl       |  | - State Machine    |  | - Publisher   | |
|  | - VersionCtrl     |  | - Approval Flow    |  | - Kafka       | |
|  | - PermissionCtrl  |  | - Governance       |  |   Topics      | |
|  | - CloneCtrl       |  |   Policy           |  |               | |
|  | - GovernanceCtrl  |  |                    |  |               | |
|  +-------------------+  +--------------------+  +---------------+ |
|                                                                   |
|  +-------------------+  +--------------------+  +---------------+ |
|  | Domain Services   |  | Permission Service |  | Metrics       | |
|  | - AssetService    |  | - Grant/Revoke     |  | - Prometheus  | |
|  | - VersionService  |  | - Effective Perms  |  | - Business    | |
|  | - CloneService    |  | - Transfer Owner   |  |   Counters    | |
|  | - LifecycleService|  | - RBAC Levels      |  |               | |
|  +-------------------+  +--------------------+  +---------------+ |
+------------------------------------------------------------------+

Asset Types

The Asset Service supports a polymorphic set of asset types through the AssetType enum:

Type	Description	Source Service
`DASHBOARD`	BI dashboards	bi-service
`QUERY`	Saved SQL queries	query-engine
`PIPELINE`	Data pipelines	pipeline-service
`ML_MODEL`	Machine learning models	ml-service
`DATASET`	Data quality datasets	data-quality-service
`SEMANTIC_MODEL`	Semantic layer models	semantic-layer
`ONTOLOGY`	Ontology definitions	ontology-service
`NOTEBOOK`	Jupyter/analysis notebooks	ml-service
`DBT_PROJECT`	dbt transformation projects	dbt-server
`TEMPLATE`	Reusable configuration templates	any service

Each asset has a URN (Uniform Resource Name) generated as urn:matih:{type}:{name}.

Version Lifecycle

Every asset version follows a governance-driven state machine:

                  submitForReview()
    DRAFT  ─────────────────────────>  IN_REVIEW
      ^                                  │    │
      │              reject()            │    │  approve() (threshold met)
      └──────────────────────────────────┘    │
                                              v
                  release()              APPROVED
    DRAFT  ─────────────────────────>  /     │
    APPROVED ────────────────────────>  RELEASED
                                          │
                  deprecate()             │
                                          v
                                     DEPRECATED
                                          │
                  retire()                │
                                          v
                                       RETIRED

Lifecycle States

State	Description	Allowed Transitions
`DRAFT`	Initial state, editable	`IN_REVIEW`, `RELEASED`
`IN_REVIEW`	Awaiting approval	`APPROVED`, `DRAFT` (rejected)
`APPROVED`	Approved, awaiting release	`RELEASED`
`RELEASED`	Live in production	`DEPRECATED`
`DEPRECATED`	Marked for sunset	`RETIRED`
`RETIRED`	End of life, read-only	(terminal)

Approval Workflow

The approval process supports configurable multi-approver governance:

Configuration	Description	Default
`minApprovers`	Minimum approvals required before auto-transition to APPROVED	1
`separationOfDuty`	Whether the submitter is prevented from approving their own submission	`true`
`autoReleaseOnApproval`	Whether to auto-release when approval threshold is met	`false`
`requireApprovalForRelease`	Whether versions must pass IN_REVIEW before release	`true`

Governance policies are configured per-tenant via the GovernancePolicyController.

Permission Model

The Asset Service implements a hierarchical permission model with six levels:

Level	View	Execute	Edit	Share	Clone	Manage
`VIEWER`	yes	-	-	-	-	-
`EXECUTOR`	yes	yes	-	-	-	-
`EDITOR`	yes	yes	yes	-	-	-
`COLLABORATOR`	yes	yes	yes	yes	yes	-
`MANAGER`	yes	yes	yes	yes	yes	yes
`OWNER`	yes	yes	yes	yes	yes	yes

Permission Resolution Order

Ownership check -- asset owner always has OWNER-level access
Explicit grant -- direct USER-type permission grants
Tenant visibility -- assets with TENANT visibility grant VIEWER to all tenant members
No access -- if none of the above match

Permissions support expiration (expiresAt) and soft revocation with audit trail.

Cloning

Assets can be cloned to create independent copies. The clone process:

Copies the asset metadata (name, description, tags, extra metadata)
Copies the latest (or specified) version's bundle manifest
Records clone provenance in the asset_clones table
Publishes an AssetCloned event

Cloning requires COLLABORATOR or higher permission on the source asset.

Event Publishing

The AssetEventPublisher publishes domain events to Kafka:

Event	Topic	Description
`AssetCreated`	`matih.asset.events`	New asset registered
`AssetUpdated`	`matih.asset.events`	Asset metadata modified
`AssetArchived`	`matih.asset.events`	Asset moved to ARCHIVED status
`VersionCreated`	`matih.asset.events`	New version created
`LifecycleTransition`	`matih.asset.lifecycle`	Version state change
`AssetShared`	`matih.asset.permissions`	Permission granted
`AssetUnshared`	`matih.asset.permissions`	Permission revoked
`OwnershipTransferred`	`matih.asset.permissions`	Owner changed
`AssetCloned`	`matih.asset.events`	Asset cloned

API Endpoints

Asset CRUD

Method	Path	Description
`POST`	`/api/v1/assets`	Create a new asset
`GET`	`/api/v1/assets`	List assets (filtered, paginated)
`GET`	`/api/v1/assets/search`	Search assets by name/description
`GET`	`/api/v1/assets/types/counts`	Count assets by type
`GET`	`/api/v1/assets/{id}`	Get asset details
`GET`	`/api/v1/assets/urn/{urn}`	Get asset by URN
`PUT`	`/api/v1/assets/{id}`	Update asset metadata
`POST`	`/api/v1/assets/{id}/archive`	Archive an asset

Versioning

Method	Path	Description
`POST`	`/api/v1/assets/{id}/versions`	Create a new version
`GET`	`/api/v1/assets/{id}/versions`	List versions (paginated)
`GET`	`/api/v1/assets/{id}/versions/{version}`	Get specific version
`GET`	`/api/v1/assets/{id}/versions/{version}/bundle`	Get bundle manifest

Lifecycle

Method	Path	Description
`POST`	`/api/v1/assets/{id}/versions/{vid}/submit-review`	Submit for review
`POST`	`/api/v1/assets/{id}/versions/{vid}/approve`	Approve version
`POST`	`/api/v1/assets/{id}/versions/{vid}/reject`	Reject version
`POST`	`/api/v1/assets/{id}/versions/{vid}/release`	Release version
`POST`	`/api/v1/assets/{id}/versions/{vid}/deprecate`	Deprecate version
`POST`	`/api/v1/assets/{id}/versions/{vid}/retire`	Retire version
`POST`	`/api/v1/assets/{id}/versions/{vid}/rollback`	Rollback to previous
`GET`	`/api/v1/assets/{id}/versions/{vid}/history`	Lifecycle audit trail

Permissions

Method	Path	Description
`POST`	`/api/v1/assets/{id}/permissions`	Grant permission
`GET`	`/api/v1/assets/{id}/permissions`	List permissions
`PUT`	`/api/v1/assets/{id}/permissions/{pid}`	Update permission
`DELETE`	`/api/v1/assets/{id}/permissions/{pid}`	Revoke permission
`GET`	`/api/v1/assets/{id}/permissions/effective`	Get effective permission
`POST`	`/api/v1/assets/{id}/transfer-ownership`	Transfer ownership

Cloning

Method	Path	Description
`POST`	`/api/v1/assets/{id}/clone`	Clone an asset
`GET`	`/api/v1/assets/{id}/clones`	List clones of an asset

Governance

Method	Path	Description
`GET`	`/api/v1/governance/policy`	Get tenant governance policy
`PUT`	`/api/v1/governance/policy`	Update governance policy

Deployment and Health

Health Endpoints

Endpoint	Description
`/actuator/health`	Composite health status
`/actuator/health/liveness`	Kubernetes liveness probe
`/actuator/health/readiness`	Kubernetes readiness probe
`/actuator/health/db`	PostgreSQL health
`/actuator/prometheus`	Prometheus metrics scrape endpoint

Prometheus Metrics

Metric	Type	Tags	Description
`matih_asset_created_total`	Counter	`type`	Assets created by asset type
`matih_asset_archived_total`	Counter	-	Assets archived
`matih_asset_version_created_total`	Counter	-	Versions created
`matih_asset_lifecycle_transition_total`	Counter	`from`, `to`	Lifecycle state transitions
`matih_asset_permission_granted_total`	Counter	`level`	Permissions granted by level
`matih_asset_clone_total`	Counter	-	Assets cloned

Database Migrations

Version	Description
V1	Initial schema: `assets`, `asset_versions`, `asset_aliases` tables
V2	Permissions and cloning: `asset_permissions`, `asset_clones` tables
V3	Version lifecycle and governance: lifecycle state columns, `version_approvals`, `lifecycle_audit_log`, `governance_policies` tables

Key Source Files

Component	Location
Asset Controller	`data-plane/asset-service/src/main/java/com/matih/asset/controller/AssetController.java`
Version Controller	`data-plane/asset-service/src/main/java/com/matih/asset/controller/AssetVersionController.java`
Lifecycle Controller	`data-plane/asset-service/src/main/java/com/matih/asset/controller/VersionLifecycleController.java`
Permission Controller	`data-plane/asset-service/src/main/java/com/matih/asset/controller/AssetPermissionController.java`
Clone Controller	`data-plane/asset-service/src/main/java/com/matih/asset/controller/AssetCloneController.java`
Governance Controller	`data-plane/asset-service/src/main/java/com/matih/asset/controller/GovernancePolicyController.java`
Asset Service	`data-plane/asset-service/src/main/java/com/matih/asset/service/AssetService.java`
Version Lifecycle Service	`data-plane/asset-service/src/main/java/com/matih/asset/service/VersionLifecycleService.java`
Permission Service	`data-plane/asset-service/src/main/java/com/matih/asset/service/AssetPermissionService.java`
State Machine Config	`data-plane/asset-service/src/main/java/com/matih/asset/config/VersionLifecycleStateMachineConfig.java`
Security Config	`data-plane/asset-service/src/main/java/com/matih/asset/config/SecurityConfig.java`
Prometheus Metrics	`data-plane/asset-service/src/main/java/com/matih/asset/config/AssetMetrics.java`
Global Exception Handler	`data-plane/asset-service/src/main/java/com/matih/asset/exception/GlobalExceptionHandler.java`
Helm Chart	`infrastructure/helm/data-plane/asset-service/`

Related Sections

Catalog Service -- Metadata discovery and search that consumes asset events
Governance -- Platform-wide governance policies that complement per-tenant asset governance
Semantic Layer -- Semantic models stored as versioned assets

API Reference Overview