@startuml logical_physical_class_diagram
!theme plain
skinparam backgroundColor #FEFEFE
skinparam classAttributeIconSize 0
skinparam shadowing false
skinparam roundcorner 10
skinparam defaultFontName "Segoe UI"

title Logical vs Physical Mechanism — Class Hierarchy

abstract class Mechanism {
  +{abstract} name: String
  +{abstract} description: String
  +{abstract} problemDomain: String
  +getDetails(): String
  +validate(): Boolean
}

abstract class LogicalMechanism extends Mechanism {
  +{abstract} capability: String
  +{abstract} constraints: List<String>
  +getAlternativeOptions(): List<PhysicalMechanism>
  +evaluateFitness(): Score
}

class PhysicalMechanism extends Mechanism {
  +vendor: String
  +version: String
  +license: LicenseType
  +deploymentConfig: DeploymentSpec
  +commit(): void
  +deploy(): DeploymentResult
}

class PersistenceLogical <<LogicalMechanism>> {
  capability = "Data Persistence"
  constraints = ["Durability", "ACID"]
}

class MessagingLogical <<LogicalMechanism>> {
  capability = "Asynchronous Communication"
  constraints = ["At-least-once delivery", "Ordering"]
}

class SecurityLogical <<LogicalMechanism>> {
  capability = "Authentication & Authorization"
  constraints = ["OAuth 2.0", "RBAC"]
}

class PostgreSQLPhysical <<PhysicalMechanism>> {
  vendor = "PostgreSQL Global Dev Group"
  version = "16.2"
  license = OPEN_SOURCE
}

class KafkaPhysical <<PhysicalMechanism>> {
  vendor = "Apache Software Foundation"
  version = "3.7.0"
  license = OPEN_SOURCE
}

class KeycloakPhysical <<PhysicalMechanism>> {
  vendor = "Red Hat"
  version = "24.0.3"
  license = OPEN_SOURCE
}

PersistenceLogical "1" --> "1..*" PhysicalMechanism : refines to >
MessagingLogical "1" --> "1..*" PhysicalMechanism : refines to >
SecurityLogical "1" --> "1..*" PhysicalMechanism : refines to >

note right of LogicalMechanism
  Technology-agnostic.
  Defines WHAT capability
  is needed, not HOW.
end note

note right of PhysicalMechanism
  Vendor-specific.
  Defines the EXACT
  implementation commitment.
end note

@enduml

@startuml component_logical_physical
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10

title Component Diagram — Logical to Physical Realization

package "Logical Layer (Technology-Agnostic)" as LogicalLayer #E8F5E9 {
  component [Persistence\nService] as LPersist #C8E6C9
  component [Messaging\nService] as LMsg #C8E6C9
  component [Identity &\nAccess Service] as LAuth #C8E6C9
  component [Notification\nService] as LNotify #C8E6C9
  component [Search\nService] as LSearch #C8E6C9
}

package "Physical Layer (Vendor-Specific)" as PhysicalLayer #E3F2FD {
  component [PostgreSQL 16\n(AWS RDS)] as PPersist #BBDEFB
  component [Apache Kafka 3.7\n(Confluent Cloud)] as PMsg #BBDEFB
  component [Keycloak 24\n(K8s Deployment)] as PAuth #BBDEFB
  component [SendGrid API v3\n(SaaS)] as PNotify #BBDEFB
  component [Elasticsearch 8.13\n(Self-hosted)] as PSearch #BBDEFB
}

LPersist ..> PPersist : <<realize>>
LMsg ..> PMsg : <<realize>>
LAuth ..> PAuth : <<realize>>
LNotify ..> PNotify : <<realize>>
LSearch ..> PSearch : <<realize>>

note bottom of LogicalLayer
  Defines interfaces and contracts.
  No vendor lock-in at this level.
end note

note bottom of PhysicalLayer
  Concrete implementations.
  Specific versions, vendors,
  and deployment targets.
end note

@enduml

@startuml package_diagram
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10

title Package Diagram — Mechanism Organization by Architectural Concern

package "System Architecture" as SysArch {

  package "Logical Mechanisms" as LogPkg #FFF9C4 {
    package "Data Access" as LogData {
      class RDBMSMechanism
      class OODBMSMechanism
      class GraphDBMechanism
    }
    package "Communication" as LogComm {
      class SyncRPCMechanism
      class AsyncMessagingMechanism
      class EventStreamingMechanism
    }
    package "Security" as LogSec {
      class AuthenticationMechanism
      class AuthorizationMechanism
      class EncryptionMechanism
    }
    package "Resilience" as LogRes {
      class RetryMechanism
      class CircuitBreakerMechanism
      class FallbackMechanism
    }
  }

  package "Physical Mechanisms" as PhysPkg #BBDEFB {
    package "Data Access Impl" as PhysData {
      class PostgreSQL16
      class MongoDB7
      class Neo4j5
    }
    package "Communication Impl" as PhysComm {
      class gRPC162
      class RabbitMQ313
      class Kafka37
    }
    package "Security Impl" as PhysSec {
      class Keycloak24
      class OPA062
      class Vault116
    }
    package "Resilience Impl" as PhysRes {
      class Resilience4j22
      class Istio122
      class Envoy130
    }
  }
}

LogData --> PhysData : <<refines>>
LogComm --> PhysComm : <<refines>>
LogSec --> PhysSec : <<refines>>
LogRes --> PhysRes : <<refines>>

@enduml

@startuml usecase_diagram
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10

title Use Case Diagram — Stakeholder Interaction with Mechanisms

left to right direction

actor "Business Analyst" as BA
actor "Solution Architect" as SA
actor "Development Lead" as DL
actor "DevOps Engineer" as DO
actor "QA Engineer" as QA

rectangle "Mechanism Management System" {

  usecase "Define Logical\nMechanisms" as UC1
  usecase "Evaluate Technology\nOptions" as UC2
  usecase "Prototype Logical\nAlternatives" as UC3
  usecase "Select Physical\nMechanism" as UC4
  usecase "Configure Physical\nDeployment" as UC5
  usecase "Validate Integration\nContracts" as UC6
  usecase "Monitor Mechanism\nPerformance" as UC7
  usecase "Substitute Physical\nImplementation" as UC8
}

BA --> UC1
SA --> UC1
SA --> UC2
SA --> UC4
DL --> UC3
DL --> UC6
DO --> UC5
DO --> UC7
QA --> UC6
QA --> UC7

UC1 ..> UC2 : <<include>>
UC2 ..> UC3 : <<include>>
UC3 ..> UC4 : <<include>>
UC4 ..> UC5 : <<include>>
UC5 ..> UC7 : <<include>>
UC7 ..> UC8 : <<extend>>

note right of UC1
  Logical mechanisms are defined
  during analysis and early design.
end note

note right of UC4
  Physical commitment happens
  after prototyping and evaluation.
end note

note right of UC8
  Substitution is possible because
  logical interfaces remain stable.
end note

@enduml

@startuml sequence_refinement
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10
skinparam sequenceMessageAlign center

title Sequence Diagram — Logical to Physical Mechanism Refinement Process

actor "Architect" as Arch
participant "Requirements\nRepository" as Req
participant "Logical Mechanism\nCatalog" as LogCat
participant "Technology\nEvaluator" as TechEval
participant "Prototype\nEnvironment" as Proto
participant "Physical Mechanism\nRegistry" as PhysReg
participant "Deployment\nPipeline" as Deploy

== Phase 1: Identify Need ==
Arch -> Req: Query required capabilities
Req --> Arch: Return capability list (e.g., "Persistence")

== Phase 2: Define Logical Mechanism ==
Arch -> LogCat: Register LogicalMechanism\n(name="Persistence",\nconstraints=[ACID, Durability])
LogCat --> Arch: Confirm registration
LogCat -> LogCat: Identify candidate families:\n[RDBMS, OODBMS, DocumentDB]

== Phase 3: Evaluate Options ==
Arch -> TechEval: Request evaluation of\nlogical candidates
TechEval -> TechEval: Score each option on:\n- Performance\n- Cost\n- Team expertise\n- Community support
TechEval --> Arch: Return ranked list:\n1. PostgreSQL (92)\n2. MySQL (85)\n3. MongoDB (78)

== Phase 4: Prototype ==
Arch -> Proto: Deploy prototype with\ntop 2 candidates
Proto -> Proto: Run benchmark suite
Proto --> Arch: Return performance metrics

== Phase 5: Commit to Physical Mechanism ==
Arch -> PhysReg: Register PhysicalMechanism\n(vendor="PostgreSQL",\nversion="16.2",\nconfig=HA_cluster)
PhysReg --> Arch: Confirm commitment
PhysReg -> Deploy: Trigger deployment pipeline
Deploy --> Arch: Deployment successful ✓

note over LogCat, PhysReg
  The logical mechanism remains
  stable even if the physical
  implementation changes later.
end note

@enduml

@startuml state_machine_lifecycle
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10

title State Machine Diagram — Mechanism Lifecycle (Logical → Physical)

[*] --> Identified : Requirement recognized

state "Logical Phase" as LogicalPhase #E8F5E9 {
  Identified --> Analyzed : Define capability\n& constraints
  Analyzed --> CandidateSelection : Identify technology\nfamilies
  CandidateSelection --> Evaluated : Score alternatives\n(performance, cost, risk)
  Evaluated --> Prototyped : Build proof-of-concept\nfor top candidates
}

state "Transition Gate" as Gate #FFF9C4
Prototyped --> Gate : Architecture\nReview Board\napproval

state "Physical Phase" as PhysicalPhase #E3F2FD {
  Gate --> Committed : Select vendor &\nversion
  Committed --> Configured : Define deployment\nspecifications
  Configured --> Deployed : Push to environment
  Deployed --> Monitored : Observe metrics\n& SLAs
}

Monitored --> Committed : Physical substitution\n(logical unchanged)
Monitored --> [*] : Mechanism retired

note right of LogicalPhase
  Technology-agnostic.
  Multiple physical options
  remain viable.
end note

note right of PhysicalPhase
  Vendor-specific.
  Commitment is made.
  Substitution requires
  migration effort.
end note

note right of Gate
  The critical decision point.
  Once crossed, the team
  commits to a physical
  implementation.
end note

@enduml

@startuml activity_decision
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10

title Activity Diagram — Physical Mechanism Selection Workflow

|Solution Architect|
start
:Identify system requirement;
:Define Logical Mechanism\n(name, capability, constraints);

fork
  :Research RDBMS options;
fork again
  :Research OODBMS options;
fork again
  :Research Document DB options;
end fork

:Compile candidate list;

|Technology Evaluator|
:Score each candidate on:\n• Performance\n• Cost\n• Scalability\n• Team expertise\n• Vendor support;

if (Any candidate scores\nabove threshold?) then (yes)
  :Select top 2-3 candidates;
  
  |Development Lead|
  :Build prototype for each;
  :Run benchmark suite;
  :Collect metrics;
  
  |Solution Architect|
  if (Clear winner\nemerges?) then (yes)
    :Select winning candidate;
  else (no)
    :Escalate to\nArchitecture Review Board;
    :ARB makes final decision;
  endif
  
  |Solution Architect|
  :Register Physical Mechanism\n(vendor, version, config);
  :Document rationale & trade-offs;
  :Update system architecture\ndocumentation;
  
  |DevOps Engineer|
  :Configure deployment pipeline;
  :Deploy to staging environment;
  :Run integration tests;
  
  if (Tests pass?) then (yes)
    :Promote to production;
    stop
  else (no)
    :Rollback;
    :Re-evaluate candidates;
    |Solution Architect|
    :Consider alternative\nphysical mechanism;
    stop
  endif
  
else (no)
  :Revisit logical mechanism\ndefinition;
  :Relax or refine constraints;
  stop
endif

@enduml

@startuml deployment_diagram
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10

title Deployment Diagram — Physical Mechanisms on Infrastructure

node "AWS Cloud" as AWS #E3F2FD {
  
  node "Application Tier\n(EKS Kubernetes 1.30)" as AppTier #BBDEFB {
    artifact "Order Service\n(Spring Boot 3.3)" as OrderSvc
    artifact "Payment Service\n(Spring Boot 3.3)" as PaySvc
    artifact "Notification Service\n(Node.js 20)" as NotifSvc
  }
  
  node "Data Tier" as DataTier #C8E6C9 {
    database "PostgreSQL 16\n(AWS RDS - Multi-AZ)" as PG
    database "Redis 7.2\n(ElastiCache Cluster)" as Redis
    database "Elasticsearch 8.13\n(3-node cluster)" as ES
  }
  
  node "Messaging Tier" as MsgTier #FFF9C4 {
    queue "Apache Kafka 3.7\n(MSK - 3 brokers)" as Kafka
    queue "Amazon SQS" as SQS
  }
  
  node "Security Tier" as SecTier #FFCDD2 {
    component "Keycloak 24\n(OIDC Provider)" as KC
    component "HashiCorp Vault 1.16\n(Secrets Management)" as Vault
  }
}

cloud "External Services" as Ext #F5F5F5 {
  component "SendGrid\n(Email Delivery)" as SG
  component "Stripe\n(Payment Gateway)" as Stripe
}

OrderSvc --> PG : <<physical>>\nJDBC
OrderSvc --> Redis : <<physical>>\nLettuce client
OrderSvc --> Kafka : <<physical>>\nProducer API
OrderSvc --> KC : <<physical>>\nOIDC
PaySvc --> Stripe : <<physical>>\nREST API
PaySvc --> PG : <<physical>>\nJDBC
NotifSvc --> SG : <<physical>>\nREST API
NotifSvc --> SQS : <<physical>>\nSDK
NotifSvc --> ES : <<physical>>\nREST client
PaySvc --> Vault : <<physical>>\nSecrets API

note right of PG
  Physical Mechanism:
  Persistence via
  PostgreSQL 16 on RDS
  (Logical: RDBMS)
end note

note right of Kafka
  Physical Mechanism:
  Messaging via
  Kafka 3.7 on MSK
  (Logical: Async Queue)
end note

note right of KC
  Physical Mechanism:
  Auth via Keycloak 24
  (Logical: Identity Provider)
end note

@enduml

@startuml communication_diagram
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10

title Communication Diagram — Order Placement Scenario (Physical Mechanisms at Work)

object "Customer" as Cust
object "API Gateway\n(Kong 3.5)" as GW
object "Order Service\n(Spring Boot)" as Order
object "PostgreSQL 16\n[RDBMS Physical]" as DB
object "Redis 7.2\n[Cache Physical]" as Cache
object "Kafka 3.7\n[Messaging Physical]" as Kafka
object "Notification Service\n(Node.js)" as Notif
object "SendGrid\n[Notification Physical]" as Email

Cust --> GW : 1: POST /orders
GW --> Order : 2: createOrder(dto)
Order --> Cache : 3: checkInventoryCache(sku)
Cache --> Order : 4: return stock level
Order --> DB : 5: INSERT order +\nUPDATE inventory
DB --> Order : 6: return confirmation
Order --> Kafka : 7: publish\n"OrderCreated" event
Kafka --> Notif : 8: consume event
Notif --> Email : 9: sendOrderConfirmation()
Email --> Cust : 10: "Your order\nis confirmed!"

note bottom of DB
  Physical Mechanism:
  PostgreSQL 16
  (fulfills logical
  Persistence)
end note

note bottom of Kafka
  Physical Mechanism:
  Apache Kafka 3.7
  (fulfills logical
  Async Messaging)
end note

note bottom of Email
  Physical Mechanism:
  SendGrid API
  (fulfills logical
  Notification)
end note

@enduml

@startuml composite_structure
!theme plain
skinparam backgroundColor #FEFEFE
skinparam shadowing false
skinparam roundcorner 10

title Composite Structure Diagram — Internal Structure of Persistence Mechanism

interface "IPersistence" as IPersistence <<logical>>
interface "IPersistenceJDBC" as IPersistenceJDBC <<physical>>

frame "PersistenceSubsystem <<boundary>>" as PersistenceSubsystem {
portin "LogicalPort\n(IPersistence)" as LPort
portout "PhysicalPort\n(IPersistenceJDBC)" as PPort

component "PersistenceAdapter <<adapter>>" as PersistenceAdapter {
[dataSource: DataSource]
[connectionPool: HikariCP]
}

component "PostgreSQLDriver <<physical>>" as PostgreSQLDriver {
[host: String = "rds.amazonaws.com"]
[port: int = 5432]
[database: String = "orderdb"]
[sslEnabled: boolean = true]
}

component "HikariConnectionPool <<physical>>" as HikariConnectionPool {
[maxPoolSize: int = 20]
[minIdle: int = 5]
[connectionTimeout: int = 30000]
}

' Internal wiring inside composite boundary
LPort --> PersistenceAdapter
PersistenceAdapter --> PPort : uses
PersistenceAdapter --> PostgreSQLDriver : delegates to
PersistenceAdapter --> HikariConnectionPool : manages
}

' External Interface Realizations
IPersistence <|.. LPort : provides PPort ..|> IPersistenceJDBC : requires

' Notes
note right of LPort
Logical interface —
technology-agnostic.
Consumers depend on this.
end note

note right of PPort
Physical interface —
vendor-specific JDBC.
Hidden behind adapter.
end note

note bottom of PersistenceAdapter
The adapter pattern allows
the physical mechanism to be
swapped without affecting
consumers of the logical port.
end note

@enduml