# baepo-cloud/viscaufs architecture

> Architecture diagram of the GitHub repository baepo-cloud/viscaufs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baepo-cloud/viscaufs
- Repository: https://github.com/baepo-cloud/viscaufs

## Overview

##### Project type and purpose
- This is a distributed filesystem project (“ViscauFS”) that consists of:
- A FUSE-based client (“filesystem/…”) that mounts a remote, lazily-loaded container image
- A gRPC server (“server/…”) that downloads, indexes, caches, and serves image layer files
- A shared library (“common/…”) providing Adaptive Radix Tree indexing, protobuf definitions, util functions

##### File structure
- Top-level directories:
- common — fsindex library, humanization, and protobuf definitions
- filesystem — FUSE client implementation and example scripts
- server — monolithic gRPC server, internal services, database migrations, Docker/image test cases
- Config and build artifacts:
- go.mod/go.sum in each module, buf.yaml in common/proto
- server/db/migrations for SQLite schema, scripts under server/script & filesystem/script
- Architectural patterns:
- client/server over gRPC
- server built with Fx dependency injection (“server/internal/fxutil”)
- layered “service” packages inside the server (filehandlerservice, fsindexservice, imgservice)

##### README for additional insights
- Pipeline overview: download layers → index each layer (Adaptive Radix Tree) → merge indexes → serve file reads on first access
- Caching: layer indexes persisted to SQLite, reused across images

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Client (MicroVM)" 
        FUSE["FUSE Client"]:::client
        SCRIPT1["Example Scripts"]:::client
    end

    subgraph "Common Library" 
        PROTO["gRPC Interface"]:::common
        FSINDEX["Adaptive Radix Tree Library"]:::common
        HUMAN["Humanize Utilities"]:::common
    end

    subgraph "ViscaUFS Server" 
        SERVERBIN["Server EntryPoint"]:::server
        CONFIG["Configuration"]:::server
        HELPER["Helpers"]:::server
        subgraph "Services"
            IMG["Image Service"]:::service
            INDEXSVC["FS-Index Service"]:::service
            FILESVC["File-Handler Service"]:::service
        end
        HANDLER["gRPC Handlers"]:::server
        SQLITE["SQLite Cache"]:::db
        SCRIPT2["Clean Env Script"]:::server
        DOCKER["Image Test Cases"]:::server
    end

    REG["Container Registry"]:::external

    FUSE -->|"gRPC"| HANDLER
    HANDLER -->|"prepare / image_ready"| IMG
    HANDLER -->|"file ops"| FILESVC
    IMG -->|"download layers"| REG
    IMG -->|"invoke index"| INDEXSVC
    INDEXSVC -->|"persist index"| SQLITE
    FILESVC -->|"lookup"| INDEXSVC

    PROTO -.-> FUSE
    PROTO -.-> HANDLER
    FSINDEX -.-> INDEXSVC
    FSINDEX -.-> FUSE
    HUMAN -.-> PROTO

    click FUSE "https://github.com/baepo-cloud/viscaufs/blob/main/filesystem/main.go"
    click FUSE "https://github.com/baepo-cloud/viscaufs/blob/main/filesystem/viscaufs/cache.go"
    click FUSE "https://github.com/baepo-cloud/viscaufs/blob/main/filesystem/viscaufs/fs.go"
    click FUSE "https://github.com/baepo-cloud/viscaufs/blob/main/filesystem/viscaufs/helper.go"
    click SCRIPT1 "https://github.com/baepo-cloud/viscaufs/blob/main/filesystem/script/overlayfs_example.sh"

    click PROTO "https://github.com/baepo-cloud/viscaufs/blob/main/common/proto/v1/rpc.proto"
    click PROTO "https://github.com/baepo-cloud/viscaufs/blob/main/common/proto/v1/types.proto"
    click PROTO "https://github.com/baepo-cloud/viscaufs/blob/main/common/proto/gen/v1/rpc.pb.go"
    click PROTO "https://github.com/baepo-cloud/viscaufs/blob/main/common/proto/gen/v1/rpc_grpc.pb.go"
    click PROTO "https://github.com/baepo-cloud/viscaufs/blob/main/common/proto/gen/v1/types.pb.go"

    click FSINDEX "https://github.com/baepo-cloud/viscaufs/blob/main/common/fsindex/index.go"
    click FSINDEX "https://github.com/baepo-cloud/viscaufs/blob/main/common/fsindex/join.go"
    click FSINDEX "https://github.com/baepo-cloud/viscaufs/blob/main/common/fsindex/serde.go"
    click FSINDEX "https://github.com/baepo-cloud/viscaufs/blob/main/common/fsindex/string.go"
    click FSINDEX "https://github.com/baepo-cloud/viscaufs/blob/main/common/fsindex/tree_helper.go"
    click FSINDEX "https://github.com/baepo-cloud/viscaufs/blob/main/common/fsindex/types.go"
    click FSINDEX "https://github.com/baepo-cloud/viscaufs/blob/main/common/fsindex/join_test.go"

    click HUMAN "https://github.com/baepo-cloud/viscaufs/blob/main/common/humanize/bytes.go"

    click SERVERBIN "https://github.com/baepo-cloud/viscaufs/blob/main/server/cmd/server/main.go"
    click CONFIG "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/config/config.go"
    click HELPER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/helper/grpc_logger_interceptor.go"
    click HELPER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/helper/sqlite_string_array.go"
    click HELPER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/helper/slices.go"
    click SCRIPT2 "https://github.com/baepo-cloud/viscaufs/blob/main/server/script/clean_env.sh"
    click DOCKER "https://github.com/baepo-cloud/viscaufs/blob/main/server/image_cases/symlink_on_prev_layer.Dockerfile"

    click IMG "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/service/imgservice/service.go"
    click INDEXSVC "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/service/fsindexservice/service.go"
    click FILESVC "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/service/filehandlerservice/service.go"

    click HANDLER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/viscaufsserver/server.go"
    click HANDLER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/viscaufsserver/handler_prepare_image.go"
    click HANDLER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/viscaufsserver/handler_image_ready.go"
    click HANDLER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/viscaufsserver/handler_getattr.go"
    click HANDLER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/viscaufsserver/handler_open.go"
    click HANDLER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/viscaufsserver/handler_read.go"
    click HANDLER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/viscaufsserver/handler_readdir.go"
    click HANDLER "https://github.com/baepo-cloud/viscaufs/blob/main/server/internal/viscaufsserver/handler_release.go"

    classDef client fill:#CCE5FF,stroke:#1E90FF,color:#000
    classDef common fill:#EDEDED,stroke:#A9A9A9,color:#000
    classDef server fill:#CCFFCC,stroke:#228B22,color:#000
    classDef service fill:#E0FFE0,stroke:#2E8B57,color:#000
    classDef db fill:#F0E68C,stroke:#DAA520,color:#000
    classDef external fill:#D3D3D3,stroke:#696969,color:#000
```
