# api-mayuri/sectoriadb architecture

> Architecture diagram of the GitHub repository api-mayuri/sectoriadb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/api-mayuri/sectoriadb
- Repository: https://github.com/api-mayuri/sectoriadb

## Overview

SectoriaDB is a Java/Spring S3-compatible object store. An S3 client sends bucket or object operations to the server; object data is chunked, hashed into blob storage, and described by a JSON manifest. The README documents these storage stages and the main capabilities, but no source excerpts were provided, so links between server handlers and internal services are not verified at code level.

Main entry points: [`sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3ObjectController.java`](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3ObjectController.java) (Object Operations), [`sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileRestoreService.java`](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileRestoreService.java) (Chunk Reads), [`sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileWriteService.java`](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileWriteService.java) (Chunk Writes), [`sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3BucketController.java`](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3BucketController.java) (Bucket Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["S3 API"]
  node_bucket_api["Bucket Operations"]
  node_object_api["Object Operations"]
  node_multipart_api["Multipart Operations"]
end

subgraph group_security["Security and Access"]
  node_auth["SigV4 Authentication<br/>[SigV4Filter.java]"]
  node_access["ACL and Policies"]
end

subgraph group_storage["Storage Engine"]
  node_pool["Storage Pools<br/>[PoolService.java]"]
  node_blob["Blob Management<br/>[BlobService.java]"]
  node_file_storage["File Storage"]
  node_chunking["Chunking"]
  node_write["Chunk Writes"]
  node_restore["Chunk Reads"]
  node_hash_table["Cuckoo Hash Table"]
  node_io_engine["Blob File I/O"]
  node_blob_data[("Blob Data Files<br/>[BlobFile.java]")]
end

subgraph group_metadata["Metadata and Audit"]
  node_manifest_repo[("Manifest Repository")]
  node_credential_service["Credential Management"]
  node_operation_log[("Operation Log")]
end

subgraph group_operations["Administration"]
  node_admin_shell["Admin Console"]
  node_resize["Automatic Resize"]
end

node_client(("S3 Client"))

node_client -->|"bucket requests"| node_bucket_api
node_client -->|"object requests"| node_object_api
node_client -->|"multipart requests"| node_multipart_api
node_auth -.->|"authenticates"| node_object_api
node_access -.->|"checks access"| node_bucket_api
node_access -.->|"checks access"| node_object_api
node_bucket_api -.->|"maps to pool"| node_pool
node_object_api -.->|"uses storage"| node_file_storage
node_multipart_api -.->|"uses storage"| node_file_storage
node_file_storage -->|"chunks files"| node_chunking
node_chunking -.->|"provides chunks"| node_write
node_write -->|"stores chunks"| node_hash_table
node_hash_table -->|"places chunks"| node_blob_data
node_write -.->|"writes data"| node_io_engine
node_restore -.->|"looks up chunks"| node_hash_table
node_restore -.->|"reads data"| node_io_engine
node_restore -.->|"reads chunks"| node_blob_data
node_object_api -.->|"uses manifests"| node_manifest_repo
node_manifest_repo -->|"records chunk keys"| node_blob_data
node_admin_shell -.->|"manages keys"| node_credential_service
node_resize -.->|"expands blobs"| node_blob

click node_bucket_api "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3BucketController.java"
click node_object_api "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3ObjectController.java"
click node_multipart_api "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3MultipartController.java"
click node_auth "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/auth/SigV4Filter.java"
click node_access "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/access/AccessControlService.java"
click node_pool "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/PoolService.java"
click node_blob "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/BlobService.java"
click node_file_storage "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/FileStorageService.java"
click node_chunking "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/DefaultChunkingService.java"
click node_write "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileWriteService.java"
click node_restore "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileRestoreService.java"
click node_hash_table "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/CuckooHashTable.java"
click node_io_engine "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/FileChannelStorageIOEngine.java"
click node_blob_data "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/model/BlobFile.java"
click node_manifest_repo "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/repository/JsonManifestRepository.java"
click node_credential_service "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/CredentialService.java"
click node_operation_log "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/OperationLogService.java"
click node_admin_shell "https://github.com/api-mayuri/sectoriadb/tree/main/sectoriadb-server/src/main/java/org/example/sectoriadb/shell"
click node_resize "https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/scheduler/AutoResizeScheduler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bucket_api,node_object_api,node_multipart_api,node_client toneBlue
class node_auth,node_access toneAmber
class node_pool,node_blob,node_file_storage,node_chunking,node_write,node_restore,node_hash_table,node_io_engine,node_blob_data toneMint
class node_manifest_repo,node_credential_service,node_operation_log toneRose
class node_admin_shell,node_resize toneIndigo
```

## Components

### S3 API

- [Bucket Operations](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3BucketController.java): `sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3BucketController.java`
- [Object Operations](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3ObjectController.java): `sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3ObjectController.java`
- [Multipart Operations](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3MultipartController.java): `sectoriadb-server/src/main/java/org/example/sectoriadb/s3/S3MultipartController.java`

### Security and Access

- [SigV4 Authentication](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/auth/SigV4Filter.java): `sectoriadb-server/src/main/java/org/example/sectoriadb/s3/auth/SigV4Filter.java`
- [ACL and Policies](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/s3/access/AccessControlService.java): `sectoriadb-server/src/main/java/org/example/sectoriadb/s3/access/AccessControlService.java`

### Storage Engine

- [Storage Pools](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/PoolService.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/PoolService.java`
- [Blob Management](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/BlobService.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/BlobService.java`
- [File Storage](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/FileStorageService.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/FileStorageService.java`
- [Chunking](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/DefaultChunkingService.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/DefaultChunkingService.java`
- [Chunk Writes](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileWriteService.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileWriteService.java`
- [Chunk Reads](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileRestoreService.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/BlobFileRestoreService.java`
- [Cuckoo Hash Table](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/CuckooHashTable.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/CuckooHashTable.java`
- [Blob File I/O](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/FileChannelStorageIOEngine.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/impl/FileChannelStorageIOEngine.java`
- [Blob Data Files](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/model/BlobFile.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/model/BlobFile.java`

### Metadata and Audit

- [Manifest Repository](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/repository/JsonManifestRepository.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/repository/JsonManifestRepository.java`
- [Credential Management](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/CredentialService.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/CredentialService.java`
- [Operation Log](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-core/src/main/java/org/example/sectoriadb/service/OperationLogService.java): `sectoriadb-core/src/main/java/org/example/sectoriadb/service/OperationLogService.java`

### Administration

- [Admin Console](https://github.com/api-mayuri/sectoriadb/tree/main/sectoriadb-server/src/main/java/org/example/sectoriadb/shell): `sectoriadb-server/src/main/java/org/example/sectoriadb/shell`
- [Automatic Resize](https://github.com/api-mayuri/sectoriadb/blob/main/sectoriadb-server/src/main/java/org/example/sectoriadb/scheduler/AutoResizeScheduler.java): `sectoriadb-server/src/main/java/org/example/sectoriadb/scheduler/AutoResizeScheduler.java`

### Other components

- **S3 Client**

## Connections

- S3 Client → Bucket Operations: bucket requests (evidence: `README.md`)
- S3 Client → Object Operations: object requests (evidence: `README.md`)
- S3 Client → Multipart Operations: multipart requests (evidence: `README.md`)
- SigV4 Authentication → Object Operations: authenticates
- ACL and Policies → Bucket Operations: checks access
- ACL and Policies → Object Operations: checks access
- Bucket Operations → Storage Pools: maps to pool
- Object Operations → File Storage: uses storage
- Multipart Operations → File Storage: uses storage
- File Storage → Chunking: chunks files (evidence: `README.md`)
- Chunking → Chunk Writes: provides chunks
- Chunk Writes → Cuckoo Hash Table: stores chunks (evidence: `README.md`)
- Cuckoo Hash Table → Blob Data Files: places chunks (evidence: `README.md`)
- Chunk Writes → Blob File I/O: writes data
- Chunk Reads → Cuckoo Hash Table: looks up chunks
- Chunk Reads → Blob File I/O: reads data
- Chunk Reads → Blob Data Files: reads chunks
- Object Operations → Manifest Repository: uses manifests
- Manifest Repository → Blob Data Files: records chunk keys (evidence: `README.md`)
- Admin Console → Credential Management: manages keys
- Automatic Resize → Blob Management: expands blobs
