@startuml

skinparam backgroundColor white
skinparam defaultFontColor black
skinparam arrowColor black
skinparam noteBackgroundColor #FFFFCC
skinparam noteBorderColor black
skinparam packageBackgroundColor #F5F5F5
skinparam packageBorderColor black
skinparam componentBackgroundColor white
skinparam componentBorderColor black
skinparam databaseBackgroundColor white
skinparam databaseBorderColor black

title Polling (MVP) vs WebSocket (Complex)

package "Polling Approach (SHIP THIS)" {
  [Browser] as B1
  [Flask API] as F1
  database "PostgreSQL" as DB1
  
  B1 -down-> F1 : HTTP GET /notifications/unread\n(every 30s)
  F1 -down-> DB1 : SELECT * WHERE user_id=? AND read=false
  DB1 -up-> F1 : JSON array
  F1 -up-> B1 : {notifications: [...]}
  
  note right of F1
    Security:
    - Session auth (existing)
    - Rate limit: 100/min
    - Sanitize with bleach
    
    Complexity: LOW
    Time: 1 week
  end note
}

package "WebSocket Approach (DON'T)" {
  [Browser] as B2
  [WebSocket Server] as WS
  [Message Queue] as MQ
  [Auth Service] as Auth
  database "PostgreSQL" as DB2
  
  B2 -down-> WS : WSS connect + JWT
  WS -right-> Auth : Validate token
  WS -down-> MQ : Subscribe user channel
  MQ -down-> DB2 : Persist?
  
  note right of WS
    Security:
    - JWT generation/rotation
    - WSS certificates
    - Connection state management
    - Stale connection cleanup
    - Token refresh logic
    - Rate limiting per connection
    
    Complexity: HIGH
    Time: 3-4 weeks
  end note
}

note bottom
  For 1000 users, 30s latency requirement:
  Polling = 33 req/s (trivial)
  
  Ship polling now, upgrade IF needed
end note

@enduml
@startuml
!theme plain

title Polling (MVP) vs WebSocket (Complex)

package "Polling Approach (SHIP THIS)" {
  [Browser] as B1
  [Flask API] as F1
  database "PostgreSQL" as DB1
  
  B1 -down-> F1 : HTTP GET /notifications/unread\n(every 30s)
  F1 -down-> DB1 : SELECT * WHERE user_id=? AND read=false
  DB1 -up-> F1 : JSON array
  F1 -up-> B1 : {notifications: [...]}
  
  note right of F1
    Security:
    - Session auth (existing)
    - Rate limit: 100/min
    - Sanitize with bleach
    
    Complexity: LOW
    Time: 1 week
  end note
}

package "WebSocket Approach (DON'T)" {
  [Browser] as B2
  [WebSocket Server] as WS
  [Message Queue] as MQ
  [Auth Service] as Auth
  database "PostgreSQL" as DB2
  
  B2 -down-> WS : WSS connect + JWT
  WS -right-> Auth : Validate token
  WS -down-> MQ : Subscribe user channel
  MQ -down-> DB2 : Persist?
  
  note right of WS
    Security:
    - JWT generation/rotation
    - WSS certificates
    - Connection state management
    - Stale connection cleanup
    - Token refresh logic
    - Rate limiting per connection
    
    Complexity: HIGH
    Time: 3-4 weeks
  end note
}

note bottom
  For 1000 users, 30s latency requirement:
  Polling = 33 req/s (trivial)
  
  Ship polling now, upgrade IF needed
end note

@enduml