# Understanding the Connection Management Service Architecture in CasaOS

> Discover the connection management service architecture in CasaOS. Learn how CasaOS handles SMB connections with its dedicated service layer for persistence, mounting, and API management.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: architecture
- Published: 2026-06-28

---

**CasaOS implements a dedicated service-layer architecture for managing SMB connections, encapsulating database persistence, system-level mounting, and HTTP API concerns behind a clean `ConnectionsService` interface.**

The connection management service architecture in CasaOS provides a robust, testable foundation for handling Samba shares. By isolating SMB operations into a distinct service layer, the codebase maintains separation between HTTP handlers, data persistence, and low-level filesystem mounts. This design leverages GORM for database operations and direct system calls for kernel-level SMB mounting.

## Core Components of the Connection Management Service

The architecture consists of three primary components that work together to provide a complete SMB connection lifecycle management solution.

### The ConnectionsService Interface

At the heart of the system lies the `ConnectionsService` interface defined in [`service/connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/connections.go). This contract establishes the public API for all connection-related operations, ensuring that HTTP handlers remain decoupled from implementation details.

```go
type ConnectionsService interface {
    GetConnectionsList() []model2.ConnectionsDBModel
    GetConnectionByHost(host string) []model2.ConnectionsDBModel
    GetConnectionByID(id string) model2.ConnectionsDBModel
    CreateConnection(*model2.ConnectionsDBModel)
    DeleteConnection(id string)
    UpdateConnection(*model2.ConnectionsDBModel)
    MountSmaba(username, host, directory, port, mountPoint, password string) error
    UnmountSmaba(mountPoint string) error
}

```

The interface exposes standard **CRUD operations** for connection metadata alongside specialized **mount/unmount methods** that handle kernel-level SMB filesystem operations.

### The connectionsStruct Implementation

The concrete implementation, `connectionsStruct`, resides in the same file ([`service/connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/connections.go)) and holds a `*gorm.DB` reference for database operations. This struct implements all interface methods, bridging the gap between high-level service calls and low-level system execution.

For persistence operations, the implementation uses standard GORM patterns. For filesystem operations, it executes system calls using `unix.Mount` and `mount.Unmount` to expose remote SMB shares under `/mnt/<host>/` directories. This encapsulation ensures that HTTP handlers never directly interact with the kernel or database driver.

### The ConnectionsDBModel Persistence Layer

Connection metadata persists through the `ConnectionsDBModel` defined in [`service/model/o_connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/model/o_connections.go). This GORM-mapped struct represents the database schema for the `o_connections` table:

```go
type ConnectionsDBModel struct {
    ID          uint   `gorm:"column:id;primary_key"`
    Updated     int64  `gorm:"autoUpdateTime"`
    Created     int64  `gorm:"autoCreateTime"`
    Username    string
    Password    string
    Host        string
    Port        string
    Status      string
    Directories string // comma-separated list
    MountPoint  string // e.g. "/mnt/<host>"
}

```

The model serves as the **single source of truth** for connection configuration, storing credentials, host information, and mount point locations required for SMB operations.

## Service Container Integration

The connection service wires into CasaOS's dependency injection container through [`service/service.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/service.go). The `NewService` function constructs a `store` struct that aggregates all sub-services, including the connection service instantiated via `NewConnectionsService(db)`.

The container exposes the service through `MyService.Connections()`, making it available to any caller without requiring direct instantiation. This pattern follows the **service-repository** architecture, allowing HTTP handlers to access connection management through a standardized facade:

```go
// Access pattern used throughout the application
service.MyService.Connections().GetConnectionsList()

```

## HTTP Handler Integration and Workflow

The [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go) file demonstrates how HTTP handlers leverage the connection management service architecture to orchestrate complex SMB workflows while maintaining clean separation of concerns.

### Listing Connections

The handler retrieves all configured connections through the service interface, converting database models to API responses:

```go
func GetSambaConnectionsList(ctx echo.Context) error {
    connections := service.MyService.Connections().GetConnectionsList()
    // ...convert to API model and return...
}

```

This approach keeps the HTTP layer agnostic to database query implementation details.

### Creating SMB Connections

Creating a connection involves multiple coordinated steps through the service layer:

```go
func PostSambaConnectionsCreate(ctx echo.Context) error {
    // Parse request → model.Connections
    dirs, err := samba.GetSambaSharesList(host, port, user, pass)
    
    // Build DB model
    conn := model2.ConnectionsDBModel{
        Username:    user,
        Password:    pass,
        Host:        host,
        Port:        port,
        Directories: strings.Join(dirs, ","),
        MountPoint:  "/mnt/" + host,
    }
    
    // Ensure mount root exists
    file.IsNotExistMkDir(conn.MountPoint)
    
    // Mount each discovered share
    for _, d := range dirs {
        mp := conn.MountPoint + "/" + d
        file.IsNotExistMkDir(mp)
        service.MyService.Connections().
            MountSmaba(user, host, d, port, mp, pass)
    }
    
    // Persist the connection record
    service.MyService.Connections().CreateConnection(&conn)
}

```

The handler orchestrates validation, share discovery, filesystem mounting, and persistence without directly managing database connections or kernel calls.

### Deleting Connections

Deletion reverses the creation process by unmounting shares before removing database records:

```go
func DeleteSambaConnections(ctx echo.Context) error {
    id := ctx.Param("id")
    conn := service.MyService.Connections().GetConnectionByID(id)
    
    shares, _ := samba.GetSambaSharesList(conn.Host, conn.Port, 
        conn.Username, conn.Password)
    
    for _, s := range shares {
        mountPath := "/mnt/" + conn.Host + "/" + s
        if service.IsMounted(mountPath) {
            service.MyService.Connections().UnmountSmaba(mountPath)
        }
    }
    
    // Clean up empty mount root
    if empty, _ := ioutil.ReadDir(conn.MountPoint); len(empty) == 0 {
        os.RemoveAll(conn.MountPoint)
    }
    
    service.MyService.Connections().DeleteConnection(id)
}

```

## Dependency Flow and Architecture Pattern

The connection management service architecture in CasaOS follows a clear dependency hierarchy:

```

HTTP Handler (route/v1/samba.go)
        ↓
   MyService.Connections()  ←─── NewService (store) ──── DB (gorm)
        ↓
   connectionsStruct methods (CRUD + mount/unmount)
        ↓
   GORM → SQLite/PostgreSQL (persisted connections)
   unix/mount → kernel (SMB mounts)

```

This design implements the **service-repository pattern**, where HTTP handlers communicate through high-level service interfaces, the service manages repository access via GORM, and system-level actions remain encapsulated within the implementation. The architecture ensures that changes to database schema, ORM configuration, or mount implementation strategies do not cascade into HTTP handler code.

## Summary

- **Interface-driven design**: The `ConnectionsService` interface in [`service/connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/connections.go) decouples HTTP handlers from implementation details, enabling testable, maintainable code.
- **Three-layer architecture**: The system separates concerns into interface definition (`ConnectionsService`), concrete implementation (`connectionsStruct`), and persistence model (`ConnectionsDBModel`).
- **Service container pattern**: `NewService` in [`service/service.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/service.go) wires the connection service into a central repository accessible via `MyService.Connections()`.
- **System call encapsulation**: Mount operations use `unix.Mount` and `mount.Unmount` internally while exposing simple method signatures to callers.
- **Complete lifecycle management**: The architecture handles connection creation, persistence, mounting, unmounting, and deletion through a cohesive API.

## Frequently Asked Questions

### How does CasaOS persist SMB connection credentials?

CasaOS stores SMB connection credentials in a database table mapped to the `ConnectionsDBModel` struct in [`service/model/o_connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/model/o_connections.go). The GORM ORM manages this persistence layer, storing username, password, host, port, and mount point information in the `o_connections` table. The `connectionsStruct` implementation in [`service/connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/connections.go) handles all database interactions through this model.

### What happens when a user creates a new SMB connection in CasaOS?

When creating a connection, the system first validates the request and probes the remote host using `samba.GetSambaSharesList` to discover available shares. It then creates a `ConnectionsDBModel` record, establishes the mount point directory under `/mnt/<host>/`, iterates over discovered shares, and calls `MountSmaba` for each share via the connection service. Finally, it persists the configuration to the database using `CreateConnection`.

### Why does CasaOS use a service interface for connection management?

The interface-based design allows CasaOS to separate HTTP route handlers from database and filesystem implementation details. This approach enables unit testing through mock implementations, supports future changes to the persistence layer or mount mechanisms without affecting API endpoints, and follows Go best practices for dependency injection. The `ConnectionsService` interface in [`service/connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/connections.go) defines this contract explicitly.

### Where does CasaOS mount SMB shares on the filesystem?

According to the source code in [`service/connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/connections.go) and [`route/v1/samba.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/samba.go), CasaOS mounts SMB shares under `/mnt/<host>/` directories, where `<host>` represents the target server hostname. Individual shares mount as subdirectories within this path (e.g., `/mnt/servername/sharename`). The `MountPoint` field in `ConnectionsDBModel` tracks these locations for subsequent unmounting and cleanup operations.