d-bis/as4-411
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c24ae925cfdd4a8ad3b91afb690e216026cf73df
as4-411/docs/architecture/data-model.md

223 lines
9.4 KiB
Markdown
Raw Normal View History

Initial commit: AS4/411 directory and discovery service for Sankofa Marketplace Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-08 08:44:20 -08:00
# Data Model
Canonical persistence model for the as4-411 directory. Aligned with [OpenAPI schemas](../api/openapi.yaml) and the [resolution algorithm](resolution-algorithm.md).
## Tables (relational baseline)
### tenants
Multi-tenant isolation. All participant data is scoped by tenant.
| Column | Type | Description |
| ---------- | --------- | ----------------- |
| id | PK | Tenant identifier |
| name | string | Display name |
| created_at | timestamp | |
| updated_at | timestamp | |
### participants
Logical entity capable of sending/receiving messages (organization, node, service).
| Column | Type | Description |
| ---------- | --------- | ---------------------- |
| id | PK | Participant identifier |
| tenant_id | FK | References tenants |
| name | string | Display name |
| created_at | timestamp | |
| updated_at | timestamp | |
### identifiers
Typed identifier bound to a participant. Used for resolution lookup and cross-mapping.
| Column | Type | Description |
| --------------- | --------- | --------------------------------------------- |
| id | PK | |
| participant_id | FK | References participants |
| identifier_type | string | See [Identifier types](#identifier-types) |
| value | string | Identifier value |
| scope | string | Optional scope (e.g. scheme) |
| priority | integer | Resolution priority (higher = preferred) |
| verified_at | timestamp | When value was last verified (e.g. SMP fetch) |
### endpoints
Routable address for a protocol domain (HTTPS URL, MLLP, MQ queue, SS7 point code, etc.).
| Column | Type | Description |
| -------------- | ------- | --------------------------------------------------- |
| id | PK | |
| participant_id | FK | References participants |
| protocol | string | as4, ss7, smp, http, mq, etc. |
| address | string | Protocol-specific address (URL, PC/SSN, queue name) |
| profile | string | Transport profile (e.g. AS4 profile name) |
| priority | integer | Ranking for resolution |
| status | string | active, inactive, draining |
### capabilities
Supported services/actions/processes/document types and constraints.
| Column | Type | Description |
| ---------------- | ------ | ----------------------- |
| id | PK | |
| participant_id | FK | References participants |
| service | string | e.g. AS4 service value |
| action | string | e.g. AS4 action |
| process | string | e.g. PEPPOL process ID |
| document_type | string | e.g. document type ID |
| constraints_json | JSON | Additional constraints |
### credentials
References to key material in vault/KMS. No private keys stored in DB.
| Column | Type | Description |
| --------------- | --------- | --------------------------- |
| id | PK | |
| participant_id | FK | References participants |
| credential_type | string | tls, sign, encrypt |
| vault_ref | string | URI to vault/KMS |
| fingerprint | string | Certificate/key fingerprint |
| valid_from | timestamp | |
| valid_to | timestamp | |
### policies
Rules controlling resolution (tenant scope, trust domains, allow/deny, priority).
| Column | Type | Description |
| --------- | ------- | -------------------- |
| id | PK | |
| tenant_id | FK | References tenants |
| rule_json | JSON | ABAC rule definition |
| effect | string | allow, deny |
| priority | integer | Evaluation order |
### audit_log
Append-only audit trail for all modifications. Optional hash-chain for tamper-evidence.
| Column | Type | Description |
| ----------- | --------- | ------------------------------------- |
| id | PK | |
| at | timestamp | |
| actor | string | Who made the change |
| action | string | create, update, delete |
| resource | string | tenants, participants, etc. |
| resource_id | string | |
| payload | JSON | Before/after or diff |
| hash_prev | string | Optional: previous row hash for chain |
## Relationships
```mermaid
erDiagram
tenants ||--o{ participants : "has"
participants ||--o{ identifiers : "has"
participants ||--o{ endpoints : "has"
participants ||--o{ capabilities : "has"
participants ||--o{ credentials : "has"
tenants ||--o{ policies : "has"
participants {
string id PK
string tenant_id FK
string name
}
identifiers {
string id PK
string participant_id FK
string identifier_type
string value
int priority
}
endpoints {
string id PK
string participant_id FK
string protocol
string address
string status
}
```
- **Tenant** scopes all participants and policies.
- **Participant** has many identifiers, endpoints, capabilities, and credential refs.
- Resolution uses identifiers to find participants, then endpoints + capabilities + policies to produce directives.
## Graph layer (edges)
Cross-mapping and provenance are modeled as an explicit graph. An **edges** table (or equivalent) represents relationships with provenance and validity.
### edges
| Column | Type | Description |
| ----------- | --------- | ------------------------------------------ |
| id | PK | |
| from_type | string | Entity type (identifier, participant, etc.) |
| from_id | string | Source entity id |
| to_type | string | Target entity type |
| to_id | string | Target entity id |
| relation | string | Relation kind (e.g. resolves_to, has_endpoint) |
| confidence | number | 0–1 confidence score |
| source | string | Provenance (internal, smp, gtt_feed, etc.) |
| valid_from | timestamp | |
| valid_to | timestamp | Optional |
Relationship types: identifier → participant (resolves_to), participant → endpoint (has_endpoint), participant → capability (has_capability). When two sources give different data for the same logical edge, conflict resolution applies.
### Conflict resolution (deterministic)
When multiple candidates or edges exist, apply in order:
1. **Explicit priority** (from endpoint/identifier priority column)
2. **Policy** (allow/deny and policy priority)
3. **Freshness** (updated_at / verified_at / valid_from)
4. **Confidence** (edge or evidence confidence score)
5. **Lexical** (stable sort by id)
Documented in [resolution-algorithm.md](resolution-algorithm.md).
## RouteDirective (output schema)
Normalized object returned by the resolver. Must match [OpenAPI RouteDirective](../api/openapi.yaml#components/schemas/RouteDirective).
| Field | Type | Description |
| ----------------- | ------ | -------------------------------------------------- |
| target_protocol | string | e.g. as4, ss7 |
| target_address | string | Endpoint address (URL, PC/SSN, etc.) |
| transport_profile | string | Profile name |
| security | object | signRequired, encryptRequired, keyRefs, algorithms |
| service_context | object | service, action, or SS7 service indicator |
| qos | object | retries, receiptsRequired, ordering |
| ttl_seconds | int | Cache TTL for this directive |
| evidence | object | source, lastVerified, confidenceScore |
## Identifier types
Reference values for `identifier_type` and resolution input. See protocol domains in the master plan.
### AS4 domain
- `as4.partyId` (with optional partyIdType in scope)
- `as4.role` (initiator/responder)
- `as4.service`, `as4.action`, `as4.mpc`
For FI-to-FI, PartyId type is often BIC or LEI (see [iso20022-over-as4](../protocols/iso20022-over-as4.md)).
### PEPPOL / SMP
- `peppol.participantId`
- `peppol.documentTypeId`
- `peppol.processId`
### SS7 domain
- `e164` (MSISDN, E.164 format)
- `gt` (Global Title)
- `pc` (Point Code)
- `ssn` (Subsystem Number)
- `mccmnc` (mobile network identifiers where relevant)
Cross-mapping examples: `as4.partyId: "0088:123456789"` ↔ `peppol.participantId: "0088:123456789"`; `e164` ↔ `gt` ↔ `pc/ssn` via GTT.
Reference in New Issue Copy Permalink