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
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

Name		Name	Last commit message	Last commit date
Latest commit History 355 Commits
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
cmd		cmd
pkg		pkg
scripts		scripts
src/typescript		src/typescript
.gitignore		.gitignore
BEST_PRACTICES.md		BEST_PRACTICES.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
models.puml		models.puml
package-lock.json		package-lock.json
package.json		package.json
update-mod.sh		update-mod.sh

License

uug-ai/models

Folders and files

Latest commit

History

Repository files navigation

Models

Features

Installation

Go

TypeScript

Quick Start

Go Usage

TypeScript Usage

Core Concepts

Automatic Type Generation

Model Categories

Usage Examples

Generating TypeScript Types

Adding New Models

Media Management Example

Device Registration Example

API Response Handling

Project Structure

Configuration

Development Setup

Environment Variables

Available Models

Core Models (pkg/models/)

API Models (pkg/api/)

Validation

Testing

Contributing

Development Guidelines

Commit Message Format

License

Dependencies

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 72

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Core Models (`pkg/models/`)

API Models (`pkg/api/`)

Packages