1 files changed, 59 insertions, 0 deletions
diff --git a/internal/models/client.go b/internal/models/client.go
new file mode 100644
index 0000000..f086594
--- /dev/null
+++ b/internal/models/client.go
@@ -0,0 +1,59 @@
+package models
+
+import "time"
+
+// ActiveSession tracks a currently active VPN connection.
+type ActiveSession struct {
+	ClientIP      string    `json:"client_ip"`      // real public IP of client (from X-Forwarded-For)
+	ServerIP      string    `json:"server_ip"`      // VPN server IP they connected to
+	NodeID        string    `json:"node_id"`        // catalog node ID
+	OS            string    `json:"os"`
+	Version       string    `json:"version"`
+	ConnectedAt   time.Time `json:"connected_at"`
+	LastHeartbeat time.Time `json:"last_seen"`
+}
+
+// StudioRecord tracks a studio's home server assignment.
+// A studio = all clients sharing the same public IP.
+type StudioRecord struct {
+	ClientIP       string    `json:"client_ip"`        // public IP = studio identifier
+	HomeServerIP   string    `json:"home_server_ip"`   // assigned "home" server
+	HomeNodeID     string    `json:"home_node_id"`
+	HomeAssignedAt time.Time `json:"home_assigned_at"` // when home was assigned
+	TotalClients   int       `json:"total_clients"`    // lifetime client count from this studio
+	LastSeen       time.Time `json:"last_seen"`
+}
+
+// ConnectRequest is sent when a client connects.
+// Server determines client_ip from X-Forwarded-For — no client_ip field needed.
+type ConnectRequest struct {
+	ServerIP string `json:"server_ip"`
+	NodeID   string `json:"node_id"`
+	OS       string `json:"os"`
+	Version  string `json:"version"`
+}
+
+// DisconnectRequest is sent when a client disconnects.
+type DisconnectRequest struct {
+	ServerIP string `json:"server_ip"`
+	NodeID   string `json:"node_id"`
+}
+
+// RecommendationResponse is returned by the recommendation endpoint.
+type RecommendationResponse struct {
+	RecommendedServerIP string `json:"recommended_server_ip"`
+	RecommendedNodeID   string `json:"recommended_node_id"`
+	RecommendedTag      string `json:"recommended_tag,omitempty"`
+	Reason              string `json:"reason"`
+	IsRebalance         bool   `json:"is_rebalance"`        // true if recommending different server than home
+	LoadInfo            string `json:"load_info"`           // human-readable load summary
+	StudioClients       int    `json:"studio_clients"`      // active clients from same studio
+}
+
+// ServerLoadInfo contains load data for all servers.
+type ServerLoadInfo struct {
+	ServerIP       string `json:"server_ip"`
+	ActiveClients  int    `json:"active_clients"`
+	LoadPercent    int    `json:"load_percent"` // 0-100
+	MaxCapacity    int    `json:"max_capacity"`
+}