models

command module

v1.5.10 Latest Latest Go to latest Published: Jun 8, 2026 License: MIT Imports: 3 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/uug-ai/models

Links

Open Source Insights

README ¶

Models

Shared data models and TypeScript type definitions for the UUG AI ecosystem.

A comprehensive Go package providing type-safe data models for media management, device control, authentication, analytics, and more. Includes automatic TypeScript type generation for seamless cross-language development.

📋 Best Practices Guide - Comprehensive guidelines for defining Go types in this repository

Features

Comprehensive Type System: 30+ models covering media, devices, authentication, analytics, and more
Cross-Language Support: Automatic TypeScript type generation from Go structs
Database Ready: Full MongoDB support with BSON tags and validation
API Optimized: JSON serialization with proper omitempty handling
Type Safety: Compile-time type checking in both Go and TypeScript
Auto-Discovery: Automatic model detection and TypeScript generation
Production Ready: Battle-tested models used in production systems

Installation

Go

go get github.com/uug-ai/models

TypeScript

npm install @uug-ai/models
# or
yarn add @uug-ai/models

Quick Start

Go Usage

package main

import (
    "github.com/uug-ai/models/pkg/models"
    "time"
)

func main() {
    // Create a media record
    media := models.Media{
        FileName:       "video_001.mp4",
        StartTimestamp: time.Now().Unix(),
        Duration:       600000, // 10 minutes in milliseconds
        DeviceId:       "camera-001",
        UserId:         "user-123",
        VideoUrl:       "https://cdn.example.com/videos/video_001.mp4",
        ThumbnailUrl:   "https://cdn.example.com/thumbs/video_001.jpg",
        SpriteUrl:      "https://cdn.example.com/sprites/video_001.jpg",
        SpriteInterval: 10,
    }
    
    // Create a device
    device := models.Device{
        Name:        "Front Door Camera",
        DeviceId:    "camera-001",
        Type:        "camera",
        Status:      "online",
        GroupId:     "group-001",
        Coordinates: &models.Coordinates{
            Latitude:  37.7749,
            Longitude: -122.4194,
        },
    }
}

TypeScript Usage

import { Media, Device, models } from '@uug-ai/models';

// Direct import
const media: Media = {
  fileName: "video_001.mp4",
  startTimestamp: 1640995200,
  duration: 600000,
  deviceId: "camera-001",
  userId: "user-123",
  videoUrl: "https://cdn.example.com/videos/video_001.mp4"
};

// Namespace import
const device: models.Device = {
  name: "Front Door Camera",
  deviceId: "camera-001",
  type: "camera",
  status: "online"
};

Core Concepts

Automatic Type Generation

This project bridges Go and TypeScript using an automated pipeline:

Go Models - Define structs in pkg/models/ with proper tags
Swagger Generation - swag scans code and generates API spec
OpenAPI Conversion - Swagger 2.0 → OpenAPI 3.x format
TypeScript Generation - OpenAPI spec → TypeScript types
Post-Processing - Add convenient exports and build

This ensures type safety across your entire stack with a single source of truth.

Model Categories

The models package organizes types into logical categories:

Media Models - Video, thumbnails, sprites, and media metadata
Device Models - Cameras, sensors, and IoT device management
Authentication - Users, tokens, permissions, and access control
Analytics - Metrics, timelines, and data analysis
Integration - Third-party service connections and webhooks
Infrastructure - Health checks, configurations, and system status

Usage Examples

Generating TypeScript Types

The primary workflow for maintaining cross-language type safety:

# Generate both OpenAPI spec and TypeScript types
npm run generate

# Or run steps individually:
npm run generate:openapi  # Go models → OpenAPI 3.x YAML
npm run generate:types    # OpenAPI YAML → TypeScript types

Generated Files:

docs/swagger.yaml - Swagger 2.0 specification (intermediate)
docs/openapi.yaml - OpenAPI 3.x specification
src/typescript/types.ts - TypeScript type definitions

Adding New Models

Create Go struct in pkg/models/:

package models

// User represents a system user
type User struct {
    ID        string `json:"id" bson:"_id,omitempty"`
    Email     string `json:"email" bson:"email" validate:"required,email"`
    Name      string `json:"name" bson:"name" validate:"required"`
    CreatedAt int64  `json:"createdAt" bson:"created_at"`
}

Reference in cmd/main.go:

// Just declare a variable or add to API endpoint
var _ = models.User{}

Generate TypeScript types:

npm run generate

No manual script updates needed! The generation pipeline automatically discovers all referenced models.

Media Management Example

package main

import (
    "context"
    "time"
    "github.com/uug-ai/models/pkg/models"
    "go.mongodb.org/mongo-driver/mongo"
)

func saveMedia(collection *mongo.Collection, deviceId string) error {
    media := models.Media{
        FileName:         "recording_2024.mp4",
        StartTimestamp:   time.Now().Add(-1 * time.Hour).Unix(),
        EndTimestamp:     time.Now().Unix(),
        Duration:         3600000, // 1 hour in milliseconds
        Provider:         "aws-s3",
        Storage:          "media-bucket",
        DeviceId:         deviceId,
        VideoUrl:         "https://cdn.example.com/videos/recording_2024.mp4",
        ThumbnailUrl:     "https://cdn.example.com/thumbs/recording_2024.jpg",
        ThumbnailFile:    "recording_2024_thumb.jpg",
        SpriteUrl:        "https://cdn.example.com/sprites/recording_2024.jpg",
        SpriteFile:       "recording_2024_sprite.jpg",
        SpriteInterval:   10,
    }
    
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    
    _, err := collection.InsertOne(ctx, media)
    return err
}

Device Registration Example

package main

import (
    "github.com/uug-ai/models/pkg/models"
    "time"
)

func registerDevice(name, deviceId string, lat, lng float64) models.Device {
    return models.Device{
        Name:        name,
        DeviceId:    deviceId,
        Type:        "camera",
        Status:      "online",
        GroupId:     "group-001",
        CreatedAt:   time.Now().Unix(),
        UpdatedAt:   time.Now().Unix(),
        Coordinates: &models.Coordinates{
            Latitude:  lat,
            Longitude: lng,
        },
        Capabilities: []string{"video", "audio", "motion-detection"},
    }
}

API Response Handling

package main

import (
    "encoding/json"
    "net/http"
    "github.com/uug-ai/models/pkg/api"
)

func healthCheckHandler(w http.ResponseWriter, r *http.Request) {
    response := api.HealthResponse{
        Status:    "healthy",
        Timestamp: time.Now().Unix(),
        Version:   "1.0.0",
    }
    
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(response)
}

func errorHandler(w http.ResponseWriter, message string, code int) {
    response := api.ErrorResponse{
        Error:      true,
        Message:    message,
        StatusCode: code,
        Timestamp:  time.Now().Unix(),
    }
    
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(code)
    json.NewEncoder(w).Encode(response)
}

Project Structure

.
├── pkg/
│   ├── models/              # Core data models
│   │   ├── media.go        # Media and video models
│   │   ├── device.go       # Device management models
│   │   ├── user.go         # User and authentication models
│   │   ├── authentication.go # Auth tokens and sessions
│   │   ├── analysis.go     # Analytics and metrics
│   │   ├── pipeline.go     # Processing pipelines
│   │   ├── integration.go  # Third-party integrations
│   │   └── ...             # 30+ additional models
│   └── api/                 # API response structures
│       ├── api.go          # Common API types
│       ├── media.go        # Media API responses
│       ├── device.go       # Device API responses
│       └── ...
├── cmd/
│   └── main.go             # Model auto-discovery entry point
├── scripts/
│   ├── auto-discover-models.js # Automatic model detection
│   └── add-type-exports.js     # TypeScript export generation
├── src/
│   └── typescript/
│       ├── types.ts        # Generated TypeScript types
│       └── package.json
├── docs/
│   ├── swagger.yaml        # Swagger 2.0 spec
│   └── openapi.yaml        # OpenAPI 3.x spec
├── go.mod
├── package.json
├── BEST_PRACTICES.md       # Type definition guidelines
└── README.md

Configuration

Development Setup

Clone the repository:

git clone https://github.com/uug-ai/models.git
cd models

Install Go dependencies:

go mod download

Install Node.js dependencies:

npm install

Install Swagger CLI:

go install github.com/swaggo/swag/cmd/swag@latest

Environment Variables

TypeScript generation can be configured via environment:

# Skip OpenAPI generation (use existing spec)
SKIP_OPENAPI=true npm run generate

# Verbose output
DEBUG=true npm run generate

Available Models

Core Models (`pkg/models/`)

Media - Video files, thumbnails, sprites, and metadata
Device - Cameras, sensors, and IoT devices
User - User accounts and profiles
Authentication - Auth tokens, sessions, and credentials
AccessToken - API access tokens and permissions
Group - User groups and organizations
Site - Physical locations and sites
Analysis - Analytics data and metrics
Pipeline - Data processing pipelines
Strategy - Processing strategies and configurations
Marker - Timeline markers and annotations
Activity - User activity logs
Alert - System alerts and notifications
Audit - Audit logs and compliance
Comment - User comments and feedback
Config - System configurations
FloorPlan - Site floor plans and layouts
Health - Health check data
Integration - Third-party integrations
Location - Geographic locations
Message - System messages and notifications
Object - Object detection results
Permission - Access permissions
Provider - Service providers
Role - User roles and capabilities
Subscription - Subscription and billing
Vault - Secure credential storage

API Models (`pkg/api/`)

ErrorResponse - Standard error responses

Selective Fields

Clients can request optional fields on certain API payloads using the include parameter in request models. For example, site option queries support include: ["metadata"] to return site metadata alongside the default fields.

HealthResponse - Health check responses
PaginationResponse - Paginated list responses
MediaResponse - Media query responses
DeviceResponse - Device query responses
AnalysisResponse - Analytics responses

Validation

Models use go-playground/validator for field validation:

type User struct {
    Email    string `json:"email" validate:"required,email"`
    Name     string `json:"name" validate:"required,min=2,max=100"`
    Age      int    `json:"age" validate:"gte=0,lte=150"`
    Role     string `json:"role" validate:"required,oneof=admin user guest"`
}

// Validate in your code
import "github.com/go-playground/validator/v10"

validate := validator.New()
err := validate.Struct(user)
if err != nil {
    // Handle validation errors
}

Common validation tags:

required - Field must be present
email - Valid email format
min=n - Minimum length/value
max=n - Maximum length/value
oneof=a b c - Must be one of specified values
gte=n,lte=n - Range validation

Testing

Run the test suite:

go test ./...

Run tests with coverage:

go test -cover ./...

Run tests for specific packages:

# Model tests
go test ./pkg/models -v

# Pipeline tests
go test ./pkg/models -run TestPipeline

Contributing

Contributions are welcome! Please follow the guidelines in BEST_PRACTICES.md when adding new models.

Development Guidelines

Fork the repository
Create a feature branch (git checkout -b feat/amazing-model)
Add your model to pkg/models/ or pkg/api/
Include proper JSON, BSON, and validation tags
Reference the model in cmd/main.go
Generate TypeScript types: npm run generate
Add tests for your model
Ensure all tests pass: go test ./...
Commit following Conventional Commits
Push to your branch (git push origin feat/amazing-model)
Open a Pull Request

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, types

Scopes:

models - Changes to Go model structs in pkg/models/
api - Changes to API response structures in pkg/api/
types - TypeScript type generation or definitions
scripts - Build/generation scripts
docs - Documentation updates

Examples:

feat(models): add sprite interval field to Media struct
fix(api): correct JSON tags for ErrorResponse message field
docs(readme): update TypeScript generation workflow
refactor(models): standardize BSON tag formatting across all structs
types: regenerate TypeScript definitions from updated Go models

License

This project is licensed under the MIT License - see the LICENSE file for details.

Dependencies

This project uses the following key libraries:

swaggo/swag - Swagger/OpenAPI generation from Go
mongo-driver - Official MongoDB Go driver
go-playground/validator - Struct validation
openapi-typescript - TypeScript generation from OpenAPI
swagger2openapi - Swagger to OpenAPI conversion

See go.mod and package.json for complete dependency lists.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: See BEST_PRACTICES.md and inline code comments

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

Path	Synopsis
pkg
api
ingest Package ingest is the transport-agnostic core that receives a producer result — from the API or the pipeline queue — and runs the right ordered, idempotent sequence of actions for its kind.	Package ingest is the transport-agnostic core that receives a producer result — from the API or the pipeline queue — and runs the right ordered, idempotent sequence of actions for its kind.
models
properties
scripts
generate-properties command generate-properties parses Go model files and generates property constants based on the bson tags found in struct fields.	generate-properties parses Go model files and generates property constants based on the bson tags found in struct fields.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL