Type Hierarchy: Arda API Proxy

Analysis of duplicate and redundant type definitions across module .types.ts files. Types are grouped by duplication pattern.

Context: System Functional Architecture

Domains, Modules and Classes

Note

Legend

• frames represent Domains
• packages represent Modules
• interface represents an endpoint in the module
• class represents additional types used in the endpoint other than the nominal entity for the interface.
• dotted arrows indicate a dependency between modules or domains
• solid arrows indicate a relationship following UML conventions (composition, inheritance)

Each Domain and Module can have its own set of types, plus a shared set for the whole platform, so there may be as many as these type sets:

- shared/types.ts
- system/
  - types.ts
  - invitation/types.ts
  - tenant/types.ts
  - user-account/types.ts
  - agent-for/types.ts
- reference/
  - shared/types.ts
  - item/types.ts
  - business-affiliate/types.ts
- resources/
  - shared/types.ts
  - kanban/types.ts
- procurement/
  - shared/types.ts
  - order/types.ts

But it is not required that they are all present.

Type location rules

1. If the type represents a concept closely tied to a module, it goes in that module’s types.ts file.
2. If the type is used by multiple modules in a domain and cannot be closely tied to one of them, it goes in the <domain>/types.ts file.
3. If the type is used by multiple domains and cannot be closely associated with any of them, it goes in the shared/types.ts file.
4. When in doubt, put it in the smallest scope possible (module —> domain —> shared) and in the “bottom” of the dependnecy hierarchy.

Import and Expoprt Rules

1. Imports should follow the dependency hierarchy and NEVER violate it.
2. Each domain should have a barrel export file that contains all neccesary symbols to use all the proxies for the domain.
3. Each module should also have a barrel export file that contains all neccessary symbols to use the proxy for the module.
4. There should be no barrel export at the root level.

Reorganization of the api-proxy repository

api-proxy/
  shared/                            // shared types and utilities
    types.ts                         // General language extension types (errors, structured wrappers, etc.)
    domain-types.ts                  // Shared Types that represent widely used concepts in the real world (manufacturing and supply chains)
  system/
    index.ts                        // barrel export for system proxy
    shared/types.ts
    invitation/
      proxy.ts
      types.ts
      utils.ts
    tenant/
      proxy.ts
      types.ts
      utils.ts
    user-account/
      proxy.ts
      types.ts
      utils.ts
    agent-for/
      proxy.ts
      types.ts
      utils.ts
  reference/
    shared/types.ts
    item/
      proxy.ts
      types.ts
      utils.ts
    business-affiliate/
      proxy.ts
      types.ts
      utils.ts
  resources/
    shared/types.ts
    kanban/
      proxy.ts
      types.ts
      utils.ts
  procurement/
    shared/types.ts
    order/
      proxy.ts
      types.ts
      utils.ts

Exact Duplicates (same name, same shape)

1. OrderMethod

11-value string union defined identically in two files.

File	Line
src/reference/item.types.ts	23–34
src/procurement/order.types.ts	24–35

type OrderMethod =
  | "UNKNOWN" | "PURCHASE_ORDER" | "EMAIL" | "PHONE" | "IN_STORE"
  | "ONLINE" | "RFQ" | "PRODUCTION" | "TASK" | "THIRD_PARTY" | "OTHER";

MP Comment

Location: `reference/item/types.ts

2. SubscriptionState / UserAccountSubscriptionState

Same 4-value union, different names.

File	Name	Line
src/system/tenant.types.ts	SubscriptionState	6
src/system/user-account.types.ts	UserAccountSubscriptionState	44

type SubscriptionState = "PENDING" | "ACTIVE" | "SUSPENDED" | "CANCELLED";

MP Comment

Location: system/types.ts

---

Structural Duplicates (different names, identical shape)

3. ResourceHome — 4 copies

Identical { fqn, networkLocator, authority } shape under 4 different names.

File	Name	Lines
src/system/tenant.types.ts	ResourceHome	12–16
src/system/user-account.types.ts	UserAccountResourceHome	30–34
src/system/agent-for.types.ts	AgentForResourceHome	14–18
src/system/invitation.types.ts	InvitationResourceHome	17–21

interface ResourceHome {
  fqn: string;
  networkLocator: string;
  authority: string;
}

MP Comment

Location: system/types.ts Name: ResourceHome

Other types replaced by imports to the shared type.

4. Contact / Identity

12 identical properties, different names.

File	Name	Lines
src/shared/domain-types.ts	Contact	84–97
src/system/user-account.types.ts	Identity	11–24

interface Contact {
  salutation?: string | null;
  firstName?: string | null;
  middleName?: string | null;
  lastName: string;
  jobTitle?: string | null;
  email?: string | null;
  phone?: string | null;
  postalAddress?: PostalAddress | null;
  emails: Record<string, string>;
  phones: Record<string, string>;
  addresses: Record<string, PostalAddress>;
  sites: Record<string, string>;
}

MP Comment

Location: shared/domain-types.ts Name: Identity Other types replaced by imports to the shared type.

5. SubscriptionReference / UserAccountSubscription

Same shape once ResourceHome and SubscriptionState are unified.

File	Name	Lines
src/system/tenant.types.ts	SubscriptionReference	19–25
src/system/user-account.types.ts	UserAccountSubscription	47–53

interface SubscriptionReference {
  state: SubscriptionState;
  acceptedTC?: number | null;
  local: string;
  revision: string;
  homes: ResourceHome[];
}

MP Comment

Location: system/types.ts Name: SubscriptionReference Other types replaced by imports to the shared type.

6. EntityReference / InvitationReference

Same shape once ResourceHome is unified.

File	Name	Lines
src/system/agent-for.types.ts	EntityReference	8–11
src/system/invitation.types.ts	InvitationReference	11–14

interface EntityReference {
  local: string;
  homes: ResourceHome[];
}

MP Comment

Location: system/types.ts Name: EntityReference Other types replaced by imports to the shared type.

7. RenderResult / KanbanPrintResult

Identical { jobId, status, url? } shape.

File	Name	Lines
src/reference/item.types.ts	RenderResult	180–184
src/resources/kanban.types.ts	KanbanPrintResult	128–132

interface RenderResult {
  jobId: string;
  status: string;
  url?: string | null;
}

MP Comment

Location: shared/domain-types.ts Name: RenderResult Other types replaced by imports to the shared type.

8. CardSize / LabelSize / BreadcrumbSize — 3 copies in one file

Same 15-value union defined three times with different names in src/reference/item.types.ts.

Name	Lines
CardSize	37–52
LabelSize	55–70
BreadcrumbSize	73–88

type PrintSize =
  | "X_SMALL" | "SMALL" | "MEDIUM" | "LARGE" | "X_LARGE"
  | "SPECIAL_01" | "SPECIAL_02" | "SPECIAL_03" | "SPECIAL_04" | "SPECIAL_05"
  | "SPECIAL_06" | "SPECIAL_07" | "SPECIAL_08" | "SPECIAL_09" | "SPECIAL_10";

MP Comment

Keep as separate types

---

Metadata Pattern Duplicates

9. Empty metadata — Record<string, never> — 3 copies

File	Name	Line
src/system/tenant.types.ts	TenantMetadata	47
src/system/user-account.types.ts	UserAccountMetadata	79
src/system/agent-for.types.ts	AgentForMetadata	40

MP Comment

Keep as separate types

10. Tenant-scoped metadata — { tenantId: string } — 4 copies

File	Name	Lines
src/system/invitation.types.ts	InvitationMetadata	49–51
src/reference/business-affiliate.types.ts	BusinessAffiliateMetadata	36–38
src/reference/item.types.ts	ItemMetadata	143–145
src/resources/kanban.types.ts	KanbanCardMetadata	86–88

MP Comment

Keep as separate types

11. Sub-entity metadata — { parentEId: string } — 2+ copies

File	Name	Lines	Notes
src/reference/business-affiliate.types.ts	BusinessRoleMetadata	66–68	{ parentEId: string }
src/reference/item.types.ts	ItemSupplyMetadata	162–164	{ parentEId: string }
src/procurement/order.types.ts	OrderLineMetadata	112–115	{ parentEId: string; rank: number } — extends pattern

MP Comment

Keep as separate types

---

Summary

#	Duplication Group	Copies	Recommended Action
1	OrderMethod	2	Move to shared
2	SubscriptionState	2	Move to shared
3	ResourceHome	4	Move to shared
4	Contact / Identity	2	Unify naming, move to shared
5	SubscriptionReference	2	Move to shared (depends on #2, #3)
6	EntityReference	2	Move to shared (depends on #3)
7	RenderResult	2	Move to shared
8	PrintSize aliases	3	Single type with aliases
9	Empty metadata	3	Shared EmptyMetadata type
10	{ tenantId } metadata	4	Shared TenantScopedMetadata type
11	{ parentEId } metadata	2–3	Shared SubEntityMetadata type

Total: ~25 redundant type definitions across 12 duplication groups.