minmon/docs/uml-guidance.md

UML Guidance

1. Use Case Diagram

Main Actor

• Admin

Main Use Cases

• Sign in
• Access protected dashboard
• View dashboard summary
• Manage servers
• Manage services
• Manage domains
• Check DNS for a domain
• Manage notes
• View notes related to a specific server
• Sign out

2. Class Diagram

Main Classes / Entities

Server

• id
• name
• primaryIpAddress
• secondaryIpAddress
• operatingSystem
• location
• provider
• description
• status
• createdAt
• updatedAt

Service

• id
• serverId
• name
• type
• internalPort
• externalPort
• protocol
• status
• description
• createdAt
• updatedAt

Domain

• id
• serviceId
• name
• expectedServerIp
• lastResolvedIp
• lastResolvedIps
• resolutionStatus
• lastCheckedAt
• remarks
• lastCheckMessage
• createdAt
• updatedAt

Note

• id
• serverId
• title
• content
• category
• createdAt
• updatedAt

Relationships

• Server 1..* Service
• Server 1..* Note
• Service 1..* Domain
• Service *..1 Server
• Domain *..1 Service
• Note *..1 Server

Implementation Notes

• Server detail page displays related notes for the selected server.
• Service forms select an existing server.
• Domain forms select an existing service.
• Note forms select an existing server.

3. Activity Diagram

Suggested activity: Check DNS from Domain List

Flow:

• Admin opens domain list
• Admin clicks the DNS status badge
• System resolves IPv4 A record(s)
• System compares resolved IPs with expectedServerIp
• System stores check result in the domain record
• System refreshes the list
• System shows MATCH, MISMATCH, or UNRESOLVED

4. State Chart Diagram

Suggested state chart: Domain DNS Status

States:

• UNRESOLVED
• MATCH
• MISMATCH

Transitions:

• DNS check success and expected IP found -> MATCH
• DNS check success and expected IP not found -> MISMATCH
• DNS resolution failure -> UNRESOLVED

5. Sequence Diagram

Suggested sequence: Create Domain and Check DNS

Objects:

• Admin
• Web UI
• tRPC API
• Database
• DNS Resolver

Flow:

• Admin opens create domain page
• UI loads available services
• Admin selects a service and submits the form
• API validates the service relationship
• API stores the domain
• Admin clicks DNS status / check action
• UI calls domains.check
• API resolves DNS A records
• API updates domain check fields in the database
• UI refetches and displays the new status

6. Collaboration Diagram

Show collaboration between:

• Admin
• Dashboard UI
• better-auth client / auth middleware
• tRPC routers
• Database
• DNS lookup module

Suggested emphasis:

• Protected route access
• CRUD coordination between UI and API
• Parent-child relationship selection in forms
• DNS checking and persistence flow
• Server detail page collaboration with note listing

7. UI/Interaction Notes for Documentation

Useful current UI details you can reflect in diagrams or captions:

• / redirects to /dashboard or /login based on session state
• Main list pages are ordered by createdAt DESC, then id DESC
• Delete actions use a two-click icon confirmation flow
• Domain DNS check is triggered from the DNS status badge in the list view