# afzal09/bucket-storage-service architecture

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

- Interactive diagram: https://gitdiagram.com/afzal09/bucket-storage-service
- Repository: https://github.com/afzal09/bucket-storage-service

## Overview

This is an S3-shaped object-storage service: clients obtain access keys, sign API requests, then manage buckets and object data through the NestJS controllers. The core path covers authorization, bucket policy checks, object metadata/version handling, and blob storage; multipart uploads stage and assemble parts before finalizing an object. Separate product branches provide encryption and presigned URLs, lifecycle processing, notifications, replication, auditing, and a dependency-free signing/streaming SDK. Some subsystem wiring is unsampled, so unverified links are dashed.

Main entry points: [`src/objects/objects.service.ts`](https://github.com/afzal09/bucket-storage-service/blob/master/src/objects/objects.service.ts) (Object versions), [`src/objects/objects.controller.ts`](https://github.com/afzal09/bucket-storage-service/blob/master/src/objects/objects.controller.ts) (Object routes), [`src/storage/storage.service.ts`](https://github.com/afzal09/bucket-storage-service/blob/master/src/storage/storage.service.ts) (Storage facade), [`src/buckets/buckets.controller.ts`](https://github.com/afzal09/bucket-storage-service/blob/master/src/buckets/buckets.controller.ts) (Bucket routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_auth_api["Key API<br/>[auth.controller.ts]"]
  node_auth["Key and signature service<br/>[auth.service.ts]"]
  node_sig_guard["Signature guard<br/>[signature.guard.ts]"]
  node_bucket_api["Bucket routes"]
  node_object_api["Object routes"]
end

subgraph group_domain["Storage domains"]
  node_buckets["Bucket management<br/>[buckets.service.ts]"]
  node_objects["Object versions<br/>[objects.service.ts]"]
  node_multipart["Multipart uploads"]
  node_storage["Storage facade<br/>[storage.service.ts]"]
  node_local_adapter["Local disk adapter"]
  node_s3_adapter["S3-compatible adapter"]
  node_metadata[("Bucket and object metadata<br/>[object.entity.ts]")]
end

subgraph group_access["Access and protection"]
  node_policy["Bucket policies<br/>[policy.service.ts]"]
  node_encryption["Data encryption"]
  node_presign["Presigned URLs"]
end

subgraph group_operations["Background operations"]
  node_lifecycle["Lifecycle processing"]
  node_scheduler["Daily scheduler"]
  node_events["Event publisher"]
  node_webhooks["Webhook dispatch"]
  node_replication["Replication"]
  node_audit["Audit logging<br/>[audit.service.ts]"]
end

subgraph group_clients["Client SDK"]
  node_sdk["TypeScript SDK<br/>[client.ts]"]
end

node_client(("Storage client"))

node_client -->|"uses"| node_sdk
node_sdk -.->|"signs requests"| node_auth_api
node_client -->|"creates keys"| node_auth_api
node_auth_api -->|"creates or revokes"| node_auth
node_sig_guard -->|"verifies signature"| node_auth
node_client -->|"manages buckets"| node_bucket_api
node_client -->|"manages objects"| node_object_api
node_bucket_api -->|"dispatches bucket actions"| node_buckets
node_bucket_api -->|"configures policy"| node_policy
node_bucket_api -->|"lists objects"| node_objects
node_object_api -->|"looks up bucket"| node_buckets
node_object_api -->|"authorizes actions"| node_policy
node_object_api -->|"generates URL"| node_presign
node_object_api -->|"dispatches object actions"| node_objects
node_object_api -->|"dispatches upload parts"| node_multipart
node_objects -->|"looks up bucket"| node_buckets
node_objects -->|"reads and writes blobs"| node_storage
node_objects -->|"encrypts data keys"| node_encryption
node_objects -->|"publishes events"| node_events
node_multipart -->|"stages and joins parts"| node_storage
node_multipart -->|"finalizes upload"| node_objects
node_storage -.->|"delegates storage"| node_local_adapter
node_storage -.->|"delegates storage"| node_s3_adapter
node_buckets -->|"queries object records"| node_metadata
node_objects -->|"persists versions"| node_metadata
node_auth -->|"protects key secrets"| node_encryption
node_scheduler -.->|"runs sweep"| node_lifecycle
node_lifecycle -->|"transitions or deletes blobs"| node_storage
node_events -.->|"dispatches notifications"| node_webhooks
node_replication -.->|"uses object service"| node_objects
node_audit -.->|"stores audit records"| node_metadata

click node_sdk "https://github.com/afzal09/bucket-storage-service/blob/master/packages/sdk/src/client.ts"
click node_auth_api "https://github.com/afzal09/bucket-storage-service/blob/master/src/auth/auth.controller.ts"
click node_auth "https://github.com/afzal09/bucket-storage-service/blob/master/src/auth/auth.service.ts"
click node_sig_guard "https://github.com/afzal09/bucket-storage-service/blob/master/src/auth/guards/signature.guard.ts"
click node_bucket_api "https://github.com/afzal09/bucket-storage-service/blob/master/src/buckets/buckets.controller.ts"
click node_object_api "https://github.com/afzal09/bucket-storage-service/blob/master/src/objects/objects.controller.ts"
click node_buckets "https://github.com/afzal09/bucket-storage-service/blob/master/src/buckets/buckets.service.ts"
click node_objects "https://github.com/afzal09/bucket-storage-service/blob/master/src/objects/objects.service.ts"
click node_multipart "https://github.com/afzal09/bucket-storage-service/blob/master/src/multipart/multipart.service.ts"
click node_storage "https://github.com/afzal09/bucket-storage-service/blob/master/src/storage/storage.service.ts"
click node_local_adapter "https://github.com/afzal09/bucket-storage-service/blob/master/src/storage/adapters/local-disk.adapter.ts"
click node_s3_adapter "https://github.com/afzal09/bucket-storage-service/blob/master/src/storage/adapters/s3-compatible.adapter.ts"
click node_metadata "https://github.com/afzal09/bucket-storage-service/blob/master/src/objects/entities/object.entity.ts"
click node_policy "https://github.com/afzal09/bucket-storage-service/blob/master/src/access-control/policy.service.ts"
click node_encryption "https://github.com/afzal09/bucket-storage-service/blob/master/src/access-control/encryption.service.ts"
click node_presign "https://github.com/afzal09/bucket-storage-service/blob/master/src/access-control/presigned-url.service.ts"
click node_lifecycle "https://github.com/afzal09/bucket-storage-service/blob/master/src/lifecycle/lifecycle.service.ts"
click node_scheduler "https://github.com/afzal09/bucket-storage-service/blob/master/src/lifecycle/lifecycle.scheduler.ts"
click node_events "https://github.com/afzal09/bucket-storage-service/blob/master/src/notifications/event-publisher.service.ts"
click node_webhooks "https://github.com/afzal09/bucket-storage-service/blob/master/src/notifications/webhook-dispatcher.service.ts"
click node_replication "https://github.com/afzal09/bucket-storage-service/blob/master/src/replication/replication.service.ts"
click node_audit "https://github.com/afzal09/bucket-storage-service/blob/master/src/audit/audit.service.ts"

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_auth_api,node_auth,node_sig_guard,node_bucket_api,node_object_api toneBlue
class node_buckets,node_objects,node_multipart,node_storage,node_local_adapter,node_s3_adapter,node_metadata,node_client toneAmber
class node_policy,node_encryption,node_presign toneMint
class node_lifecycle,node_scheduler,node_events,node_webhooks,node_replication,node_audit toneRose
class node_sdk toneIndigo
```

## Components

### API and identity

- [Key API](https://github.com/afzal09/bucket-storage-service/blob/master/src/auth/auth.controller.ts): `src/auth/auth.controller.ts`
- [Key and signature service](https://github.com/afzal09/bucket-storage-service/blob/master/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [Signature guard](https://github.com/afzal09/bucket-storage-service/blob/master/src/auth/guards/signature.guard.ts): `src/auth/guards/signature.guard.ts`
- [Bucket routes](https://github.com/afzal09/bucket-storage-service/blob/master/src/buckets/buckets.controller.ts): `src/buckets/buckets.controller.ts`
- [Object routes](https://github.com/afzal09/bucket-storage-service/blob/master/src/objects/objects.controller.ts): `src/objects/objects.controller.ts`

### Storage domains

- [Bucket management](https://github.com/afzal09/bucket-storage-service/blob/master/src/buckets/buckets.service.ts): `src/buckets/buckets.service.ts`
- [Object versions](https://github.com/afzal09/bucket-storage-service/blob/master/src/objects/objects.service.ts): `src/objects/objects.service.ts`
- [Multipart uploads](https://github.com/afzal09/bucket-storage-service/blob/master/src/multipart/multipart.service.ts): `src/multipart/multipart.service.ts`
- [Storage facade](https://github.com/afzal09/bucket-storage-service/blob/master/src/storage/storage.service.ts): `src/storage/storage.service.ts`
- [Local disk adapter](https://github.com/afzal09/bucket-storage-service/blob/master/src/storage/adapters/local-disk.adapter.ts): `src/storage/adapters/local-disk.adapter.ts`
- [S3-compatible adapter](https://github.com/afzal09/bucket-storage-service/blob/master/src/storage/adapters/s3-compatible.adapter.ts): `src/storage/adapters/s3-compatible.adapter.ts`
- [Bucket and object metadata](https://github.com/afzal09/bucket-storage-service/blob/master/src/objects/entities/object.entity.ts): `src/objects/entities/object.entity.ts`

### Access and protection

- [Bucket policies](https://github.com/afzal09/bucket-storage-service/blob/master/src/access-control/policy.service.ts): `src/access-control/policy.service.ts`
- [Data encryption](https://github.com/afzal09/bucket-storage-service/blob/master/src/access-control/encryption.service.ts): `src/access-control/encryption.service.ts`
- [Presigned URLs](https://github.com/afzal09/bucket-storage-service/blob/master/src/access-control/presigned-url.service.ts): `src/access-control/presigned-url.service.ts`

### Background operations

- [Lifecycle processing](https://github.com/afzal09/bucket-storage-service/blob/master/src/lifecycle/lifecycle.service.ts): `src/lifecycle/lifecycle.service.ts`
- [Daily scheduler](https://github.com/afzal09/bucket-storage-service/blob/master/src/lifecycle/lifecycle.scheduler.ts): `src/lifecycle/lifecycle.scheduler.ts`
- [Event publisher](https://github.com/afzal09/bucket-storage-service/blob/master/src/notifications/event-publisher.service.ts): `src/notifications/event-publisher.service.ts`
- [Webhook dispatch](https://github.com/afzal09/bucket-storage-service/blob/master/src/notifications/webhook-dispatcher.service.ts): `src/notifications/webhook-dispatcher.service.ts`
- [Replication](https://github.com/afzal09/bucket-storage-service/blob/master/src/replication/replication.service.ts): `src/replication/replication.service.ts`
- [Audit logging](https://github.com/afzal09/bucket-storage-service/blob/master/src/audit/audit.service.ts): `src/audit/audit.service.ts`

### Client SDK

- [TypeScript SDK](https://github.com/afzal09/bucket-storage-service/blob/master/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`

### Other components

- **Storage client**

## Connections

- Storage client → TypeScript SDK: uses (evidence: `README.md`)
- TypeScript SDK → Key API: signs requests
- Storage client → Key API: creates keys (evidence: `README.md`)
- Key API → Key and signature service: creates or revokes (evidence: `src/auth/auth.controller.ts`)
- Signature guard → Key and signature service: verifies signature (evidence: `src/auth/guards/signature.guard.ts`)
- Storage client → Bucket routes: manages buckets (evidence: `README.md`)
- Storage client → Object routes: manages objects (evidence: `README.md`)
- Bucket routes → Bucket management: dispatches bucket actions (evidence: `src/buckets/buckets.controller.ts`)
- Bucket routes → Bucket policies: configures policy (evidence: `src/buckets/buckets.controller.ts`)
- Bucket routes → Object versions: lists objects (evidence: `src/buckets/buckets.controller.ts`)
- Object routes → Bucket management: looks up bucket (evidence: `src/objects/objects.controller.ts`)
- Object routes → Bucket policies: authorizes actions (evidence: `src/objects/objects.controller.ts`)
- Object routes → Presigned URLs: generates URL (evidence: `src/objects/objects.controller.ts`)
- Object routes → Object versions: dispatches object actions (evidence: `src/objects/objects.controller.ts`)
- Object routes → Multipart uploads: dispatches upload parts (evidence: `src/objects/objects.controller.ts`)
- Object versions → Bucket management: looks up bucket (evidence: `src/objects/objects.service.ts`)
- Object versions → Storage facade: reads and writes blobs (evidence: `src/objects/objects.service.ts`)
- Object versions → Data encryption: encrypts data keys (evidence: `src/objects/objects.service.ts`)
- Object versions → Event publisher: publishes events (evidence: `src/objects/objects.service.ts`)
- Multipart uploads → Storage facade: stages and joins parts (evidence: `src/multipart/multipart.service.ts`)
- Multipart uploads → Object versions: finalizes upload (evidence: `src/multipart/multipart.service.ts`)
- Storage facade → Local disk adapter: delegates storage
- Storage facade → S3-compatible adapter: delegates storage
- Bucket management → Bucket and object metadata: queries object records (evidence: `src/buckets/buckets.service.ts`)
- Object versions → Bucket and object metadata: persists versions (evidence: `src/objects/objects.service.ts`)
- Key and signature service → Data encryption: protects key secrets (evidence: `src/auth/auth.service.ts`)
- Daily scheduler → Lifecycle processing: runs sweep
- Lifecycle processing → Storage facade: transitions or deletes blobs (evidence: `src/lifecycle/lifecycle.service.ts`)
- Event publisher → Webhook dispatch: dispatches notifications (evidence: `src/notifications/webhook-dispatcher.service.ts`)
- Replication → Object versions: uses object service (evidence: `src/replication/replication.service.ts`)
- Audit logging → Bucket and object metadata: stores audit records
