# jnrgxx/object-storage-service architecture

> Architecture diagram of the GitHub repository jnrgxx/object-storage-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jnrgxx/object-storage-service
- Repository: https://github.com/jnrgxx/object-storage-service

## Overview

This is a work-in-progress S3-inspired object storage service. The intended user workflow is to create or select a bucket, upload files, manage their metadata, then download or delete objects; the backend separates HTTP controllers, business services, database metadata, and disk storage. The React entry screen is still a Vite starter, not an implemented storage UI. Several capabilities are documented or declared but their full routes and implementation were not sampled, so unsupported links are omitted.

Main entry points: [`backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java`](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java) (Bucket Management), [`backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java`](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java) (Object Operations), [`backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/BucketMapper.java`](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/BucketMapper.java) (Bucket Mapping), [`backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/StorageServiceImpl.java`](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/StorageServiceImpl.java) (Disk Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_bucket_api["Bucket API"]
  node_object_api["Object API"]
  node_error_handler["API Errors"]
end

subgraph group_domain["Bucket and Object Domain"]
  node_bucket_logic["Bucket Management"]
  node_object_logic["Object Operations"]
  node_bucket_mapper["Bucket Mapping<br/>[BucketMapper.java]"]
  node_object_mapper["Object Mapping<br/>[ObjectMapper.java]"]
  node_bucket_dto["Bucket DTOs<br/>[BucketDto.java]"]
  node_create_bucket["Create Bucket Request"]
  node_object_dto["Object Response"]
end

subgraph group_persistence["Metadata Persistence"]
  node_bucket_entity["Bucket Record<br/>[Bucket.java]"]
  node_object_entity["Object Record<br/>[StorageObject.java]"]
  node_bucket_repo["Bucket Repository"]
  node_object_repo["Object Repository"]
  node_metadata_db[("PostgreSQL")]
end

subgraph group_files["File Storage"]
  node_storage_logic["Disk Storage"]
  node_storage_config["Storage Configuration<br/>[StorageConfig.java]"]
  node_disk[("Local Filesystem")]
end

node_client(("API Client"))

node_client -->|"manages buckets"| node_bucket_api
node_client -->|"manages files"| node_object_api
node_bucket_api -->|"dispatches"| node_bucket_logic
node_object_api -->|"dispatches"| node_object_logic
node_bucket_logic -->|"reads and writes"| node_bucket_repo
node_bucket_logic -->|"deletes bucket objects"| node_object_repo
node_bucket_logic -->|"deletes bucket files"| node_storage_logic
node_bucket_logic -->|"maps data"| node_bucket_mapper
node_object_logic -->|"checks bucket"| node_bucket_repo
node_object_logic -->|"reads and writes"| node_object_repo
node_object_logic -->|"stores, loads, deletes"| node_storage_logic
node_object_logic -->|"maps responses"| node_object_mapper
node_bucket_mapper -->|"maps entity"| node_bucket_entity
node_bucket_mapper -->|"maps DTO"| node_bucket_dto
node_bucket_mapper -->|"maps request"| node_create_bucket
node_object_mapper -.->|"maps entity"| node_object_entity
node_object_mapper -.->|"maps response"| node_object_dto
node_bucket_repo -.->|"persists records"| node_metadata_db
node_object_repo -.->|"persists records"| node_metadata_db
node_storage_logic -->|"uses settings"| node_storage_config
node_storage_logic -.->|"reads and writes files"| node_disk

click node_bucket_api "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/controller/BucketController.java"
click node_object_api "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/controller/ObjectController.java"
click node_error_handler "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/exception/GlobalExceptionHandler.java"
click node_bucket_logic "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java"
click node_object_logic "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java"
click node_bucket_mapper "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/BucketMapper.java"
click node_object_mapper "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/ObjectMapper.java"
click node_bucket_dto "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/BucketDto.java"
click node_create_bucket "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/CreateBucketRequest.java"
click node_object_dto "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/ObjectResponseDto.java"
click node_bucket_entity "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/entity/Bucket.java"
click node_object_entity "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/entity/StorageObject.java"
click node_bucket_repo "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/repository/BucketRepository.java"
click node_object_repo "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/repository/ObjectRepository.java"
click node_storage_logic "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/StorageServiceImpl.java"
click node_storage_config "https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/config/StorageConfig.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_error_handler,node_client toneBlue
class node_bucket_logic,node_object_logic,node_bucket_mapper,node_object_mapper,node_bucket_dto,node_create_bucket,node_object_dto toneAmber
class node_bucket_entity,node_object_entity,node_bucket_repo,node_object_repo,node_metadata_db toneMint
class node_storage_logic,node_storage_config,node_disk toneRose
```

## Components

### HTTP API

- [Bucket API](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/controller/BucketController.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/controller/BucketController.java`
- [Object API](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/controller/ObjectController.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/controller/ObjectController.java`
- [API Errors](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/exception/GlobalExceptionHandler.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/exception/GlobalExceptionHandler.java`

### Bucket and Object Domain

- [Bucket Management](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java`
- [Object Operations](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java`
- [Bucket Mapping](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/BucketMapper.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/BucketMapper.java`
- [Object Mapping](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/ObjectMapper.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/ObjectMapper.java`
- [Bucket DTOs](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/BucketDto.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/BucketDto.java`
- [Create Bucket Request](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/CreateBucketRequest.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/CreateBucketRequest.java`
- [Object Response](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/ObjectResponseDto.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/dto/ObjectResponseDto.java`

### Metadata Persistence

- [Bucket Record](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/entity/Bucket.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/entity/Bucket.java`
- [Object Record](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/entity/StorageObject.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/domain/entity/StorageObject.java`
- [Bucket Repository](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/repository/BucketRepository.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/repository/BucketRepository.java`
- [Object Repository](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/repository/ObjectRepository.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/repository/ObjectRepository.java`
- **PostgreSQL**

### File Storage

- [Disk Storage](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/StorageServiceImpl.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/StorageServiceImpl.java`
- [Storage Configuration](https://github.com/jnrgxx/object-storage-service/blob/main/backend/src/main/java/com/object_storage_service/object_storage_service_api/config/StorageConfig.java): `backend/src/main/java/com/object_storage_service/object_storage_service_api/config/StorageConfig.java`
- **Local Filesystem**

### Other components

- **API Client**

## Connections

- API Client → Bucket API: manages buckets (evidence: `README.md`)
- API Client → Object API: manages files (evidence: `README.md`)
- Bucket API → Bucket Management: dispatches (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/controller/BucketController.java`)
- Object API → Object Operations: dispatches (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/controller/ObjectController.java`)
- Bucket Management → Bucket Repository: reads and writes (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java`)
- Bucket Management → Object Repository: deletes bucket objects (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java`)
- Bucket Management → Disk Storage: deletes bucket files (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java`)
- Bucket Management → Bucket Mapping: maps data (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/BucketServiceImpl.java`)
- Object Operations → Bucket Repository: checks bucket (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java`)
- Object Operations → Object Repository: reads and writes (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java`)
- Object Operations → Disk Storage: stores, loads, deletes (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java`)
- Object Operations → Object Mapping: maps responses (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/ObjectServiceImpl.java`)
- Bucket Mapping → Bucket Record: maps entity (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/BucketMapper.java`)
- Bucket Mapping → Bucket DTOs: maps DTO (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/BucketMapper.java`)
- Bucket Mapping → Create Bucket Request: maps request (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/BucketMapper.java`)
- Object Mapping → Object Record: maps entity (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/ObjectMapper.java`)
- Object Mapping → Object Response: maps response (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/mapper/ObjectMapper.java`)
- Bucket Repository → PostgreSQL: persists records
- Object Repository → PostgreSQL: persists records
- Disk Storage → Storage Configuration: uses settings (evidence: `backend/src/main/java/com/object_storage_service/object_storage_service_api/service/impl/StorageServiceImpl.java`)
- Disk Storage → Local Filesystem: reads and writes files