# harit3009/docker-fs architecture

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

- Interactive diagram: https://gitdiagram.com/harit3009/docker-fs
- Repository: https://github.com/harit3009/docker-fs

## Overview

docker-FS is a NestJS cloud file system: authenticated users manage hierarchical files and folders, upload or download S3 objects, and search or chat over indexed document content. The documented processing stages include S3-triggered Kafka work for metadata creation, zip extraction, document parsing, embeddings, and indexing; trash cleanup and group membership are additional capabilities. Sampled excerpts establish API-to-storage and chat retrieval calls. Kafka/Lambda event wiring and several processing links are documented but their implementations were not sampled, so those edges are limited to documented relationships.

Main entry points: [`src/prisma/prisma.service.ts`](https://github.com/harit3009/docker-fs/blob/main/src/prisma/prisma.service.ts) (Prisma service), [`src/bridge/ai-retrieval/ai-retrieval.service.ts`](https://github.com/harit3009/docker-fs/blob/main/src/bridge/ai-retrieval/ai-retrieval.service.ts) (AI retrieval), [`src/bridge/kafka/kafka.service.ts`](https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka.service.ts) (Kafka bridge), [`src/bridge/embedding/embedding.service.ts`](https://github.com/harit3009/docker-fs/blob/main/src/bridge/embedding/embedding.service.ts) (Embedding service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_auth_api["Auth API<br/>[auth.controller.ts]"]
  node_auth_service["Login service<br/>[auth.service.ts]"]
  node_jwt["JWT strategy"]
end

subgraph group_storage["File storage"]
  node_files_api["File system API"]
  node_s3_service["S3 integration"]
  node_prisma["Prisma service<br/>[prisma.service.ts]"]
end

subgraph group_processing["Document processing"]
  node_kafka["Kafka bridge<br/>[kafka.service.ts]"]
  node_s3_trigger["S3 event trigger"]
  node_create_consumer["File creation consumer"]
  node_zip_consumer["Zip extraction"]
  node_delete_consumer["Delete consumer"]
  node_index_service["Indexing service"]
  node_pdf_parser["PDF parser"]
  node_dlq["S3 event DLQ processor"]
end

subgraph group_search["Search and chat"]
  node_embedding["Embedding service"]
  node_opensearch_service["OpenSearch service"]
  node_search_chat["AI retrieval"]
end

subgraph group_access["Groups and cleanup"]
  node_groups_api["Group API"]
  node_trash["Trash scheduler"]
end

node_user(("User"))
node_google["Google OAuth"]
node_s3[("S3 object store")]
node_db[("PostgreSQL metadata")]
node_opensearch[("OpenSearch indexes")]
node_chat_model["Chat and embedding APIs"]

node_user -->|"signs in"| node_auth_api
node_auth_api -->|"authenticates with"| node_google
node_auth_api -->|"handles login"| node_auth_service
node_auth_service -->|"reads/writes users"| node_prisma
node_auth_api -->|"guards requests"| node_jwt
node_user -->|"manages files"| node_files_api
node_files_api -->|"reads/writes metadata"| node_prisma
node_files_api -->|"requests signed URLs"| node_s3_service
node_s3_service -->|"reads/writes objects"| node_s3
node_prisma -->|"persists metadata"| node_db
node_s3 -.->|"emits object events"| node_s3_trigger
node_s3_trigger -.->|"publishes work"| node_kafka
node_kafka -.->|"dispatches events"| node_create_consumer
node_kafka -.->|"dispatches events"| node_zip_consumer
node_kafka -.->|"dispatches events"| node_delete_consumer
node_create_consumer -.->|"records metadata"| node_prisma
node_zip_consumer -.->|"extracts objects"| node_s3_service
node_create_consumer -.->|"requests indexing"| node_index_service
node_index_service -.->|"extracts PDF text"| node_pdf_parser
node_pdf_parser -->|"reads object stream"| node_s3_service
node_index_service -.->|"generates vectors"| node_embedding
node_index_service -.->|"indexes content"| node_opensearch_service
node_embedding -->|"requests embeddings"| node_chat_model
node_opensearch_service -->|"indexes/searches"| node_opensearch
node_user -->|"searches and chats"| node_search_chat
node_search_chat -->|"embeds query"| node_embedding
node_search_chat -->|"retrieves chunks"| node_opensearch_service
node_search_chat -->|"reads metadata"| node_prisma
node_search_chat -->|"submits conversation"| node_embedding
node_embedding -->|"requests chat response"| node_chat_model
node_user -->|"manages groups"| node_groups_api
node_groups_api -->|"reads/writes membership"| node_prisma
node_trash -.->|"cleans expired trash"| node_prisma
node_trash -.->|"deletes objects"| node_s3_service
node_dlq -.->|"processes failed events"| node_kafka

click node_auth_api "https://github.com/harit3009/docker-fs/blob/main/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/harit3009/docker-fs/blob/main/src/auth/auth.service.ts"
click node_jwt "https://github.com/harit3009/docker-fs/blob/main/src/auth/jwt-verifier.strategy.ts"
click node_files_api "https://github.com/harit3009/docker-fs/blob/main/src/file-system/file-system.controller.ts"
click node_s3_service "https://github.com/harit3009/docker-fs/blob/main/src/s3-module/s3-service.service.ts"
click node_prisma "https://github.com/harit3009/docker-fs/blob/main/src/prisma/prisma.service.ts"
click node_kafka "https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka.service.ts"
click node_s3_trigger "https://github.com/harit3009/docker-fs/blob/main/src/lambdas/s3_event_trigger.ts"
click node_create_consumer "https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka-create/kafka-create-file.ts"
click node_zip_consumer "https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka-extract-zip/kafka-extract-zip.service.ts"
click node_delete_consumer "https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka-delete-consumer/kafka-delete-consumer.service.ts"
click node_index_service "https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka-create/kafka-index-file-service.service.ts"
click node_pdf_parser "https://github.com/harit3009/docker-fs/blob/main/src/bridge/pdf-parser/pdf-parser.service.ts"
click node_embedding "https://github.com/harit3009/docker-fs/blob/main/src/bridge/embedding/embedding.service.ts"
click node_opensearch_service "https://github.com/harit3009/docker-fs/blob/main/src/bridge/open-search/open-search.service.ts"
click node_search_chat "https://github.com/harit3009/docker-fs/blob/main/src/bridge/ai-retrieval/ai-retrieval.service.ts"
click node_groups_api "https://github.com/harit3009/docker-fs/blob/main/src/user-groups/group-controller.controller.ts"
click node_trash "https://github.com/harit3009/docker-fs/blob/main/src/bridge/delete-trash-scheduler/delete-trash-scheduler.service.ts"
click node_dlq "https://github.com/harit3009/docker-fs/blob/main/src/lambdas/s3_event_dlq_processor.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_service,node_jwt,node_user toneBlue
class node_files_api,node_s3_service,node_prisma,node_s3,node_db,node_opensearch toneAmber
class node_kafka,node_s3_trigger,node_create_consumer,node_zip_consumer,node_delete_consumer,node_index_service,node_pdf_parser,node_dlq,node_chat_model toneMint
class node_embedding,node_opensearch_service,node_search_chat toneRose
class node_groups_api,node_trash,node_google toneIndigo
```

## Components

### API and identity

- [Auth API](https://github.com/harit3009/docker-fs/blob/main/src/auth/auth.controller.ts): `src/auth/auth.controller.ts`
- [Login service](https://github.com/harit3009/docker-fs/blob/main/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [JWT strategy](https://github.com/harit3009/docker-fs/blob/main/src/auth/jwt-verifier.strategy.ts): `src/auth/jwt-verifier.strategy.ts`

### File storage

- [File system API](https://github.com/harit3009/docker-fs/blob/main/src/file-system/file-system.controller.ts): `src/file-system/file-system.controller.ts`
- [S3 integration](https://github.com/harit3009/docker-fs/blob/main/src/s3-module/s3-service.service.ts): `src/s3-module/s3-service.service.ts`
- [Prisma service](https://github.com/harit3009/docker-fs/blob/main/src/prisma/prisma.service.ts): `src/prisma/prisma.service.ts`

### Document processing

- [Kafka bridge](https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka.service.ts): `src/bridge/kafka/kafka.service.ts`
- [S3 event trigger](https://github.com/harit3009/docker-fs/blob/main/src/lambdas/s3_event_trigger.ts): `src/lambdas/s3_event_trigger.ts`
- [File creation consumer](https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka-create/kafka-create-file.ts): `src/bridge/kafka/kafka-create/kafka-create-file.ts`
- [Zip extraction](https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka-extract-zip/kafka-extract-zip.service.ts): `src/bridge/kafka/kafka-extract-zip/kafka-extract-zip.service.ts`
- [Delete consumer](https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka-delete-consumer/kafka-delete-consumer.service.ts): `src/bridge/kafka/kafka-delete-consumer/kafka-delete-consumer.service.ts`
- [Indexing service](https://github.com/harit3009/docker-fs/blob/main/src/bridge/kafka/kafka-create/kafka-index-file-service.service.ts): `src/bridge/kafka/kafka-create/kafka-index-file-service.service.ts`
- [PDF parser](https://github.com/harit3009/docker-fs/blob/main/src/bridge/pdf-parser/pdf-parser.service.ts): `src/bridge/pdf-parser/pdf-parser.service.ts`
- [S3 event DLQ processor](https://github.com/harit3009/docker-fs/blob/main/src/lambdas/s3_event_dlq_processor.ts): `src/lambdas/s3_event_dlq_processor.ts`

### Search and chat

- [Embedding service](https://github.com/harit3009/docker-fs/blob/main/src/bridge/embedding/embedding.service.ts): `src/bridge/embedding/embedding.service.ts`
- [OpenSearch service](https://github.com/harit3009/docker-fs/blob/main/src/bridge/open-search/open-search.service.ts): `src/bridge/open-search/open-search.service.ts`
- [AI retrieval](https://github.com/harit3009/docker-fs/blob/main/src/bridge/ai-retrieval/ai-retrieval.service.ts): `src/bridge/ai-retrieval/ai-retrieval.service.ts`

### Groups and cleanup

- [Group API](https://github.com/harit3009/docker-fs/blob/main/src/user-groups/group-controller.controller.ts): `src/user-groups/group-controller.controller.ts`
- [Trash scheduler](https://github.com/harit3009/docker-fs/blob/main/src/bridge/delete-trash-scheduler/delete-trash-scheduler.service.ts): `src/bridge/delete-trash-scheduler/delete-trash-scheduler.service.ts`

### Other components

- **User**
- **Google OAuth**
- **S3 object store**
- **PostgreSQL metadata**
- **OpenSearch indexes**
- **Chat and embedding APIs**

## Connections

- User → Auth API: signs in
- Auth API → Google OAuth: authenticates with
- Auth API → Login service: handles login
- Login service → Prisma service: reads/writes users
- Auth API → JWT strategy: guards requests
- User → File system API: manages files
- File system API → Prisma service: reads/writes metadata
- File system API → S3 integration: requests signed URLs
- S3 integration → S3 object store: reads/writes objects
- Prisma service → PostgreSQL metadata: persists metadata
- S3 object store → S3 event trigger: emits object events
- S3 event trigger → Kafka bridge: publishes work
- Kafka bridge → File creation consumer: dispatches events
- Kafka bridge → Zip extraction: dispatches events
- Kafka bridge → Delete consumer: dispatches events
- File creation consumer → Prisma service: records metadata
- Zip extraction → S3 integration: extracts objects
- File creation consumer → Indexing service: requests indexing
- Indexing service → PDF parser: extracts PDF text
- PDF parser → S3 integration: reads object stream
- Indexing service → Embedding service: generates vectors
- Indexing service → OpenSearch service: indexes content
- Embedding service → Chat and embedding APIs: requests embeddings
- OpenSearch service → OpenSearch indexes: indexes/searches
- User → AI retrieval: searches and chats
- AI retrieval → Embedding service: embeds query
- AI retrieval → OpenSearch service: retrieves chunks
- AI retrieval → Prisma service: reads metadata
- AI retrieval → Embedding service: submits conversation
- Embedding service → Chat and embedding APIs: requests chat response
- User → Group API: manages groups
- Group API → Prisma service: reads/writes membership
- Trash scheduler → Prisma service: cleans expired trash
- Trash scheduler → S3 integration: deletes objects
- S3 event DLQ processor → Kafka bridge: processes failed events