# thesynthax/dropifi architecture

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

- Interactive diagram: https://gitdiagram.com/thesynthax/dropifi
- Repository: https://github.com/thesynthax/dropifi

## Overview

1. This repo is split into two Node/TypeScript codebases: `server/` is the current implementation of Dropifi v2, and `dropifi-v1/` is a separate legacy snapshot of the earlier version. For an architecture diagram, treat `server/` as the active system and `dropifi-v1/` as historical context.

2. The active service is a backend file-sharing system. The main runtime entrypoint is `server/src/server.ts`, which boots the HTTP server and wires together the rest of the application. There is no frontend in this repository.

3. Configuration is centralized under `server/config/config.json`, with the service code reading that config during startup. The config likely controls storage backend selection, Redis usage, cleanup behavior, and other deployment-specific settings.

4. The application is organized around a small set of business services in `server/src/services/`: validation, password handling, rate limiting, expiry logic, and cleanup orchestration. These are the main domain boundaries and are the right boxes to place in the middle of an architecture diagram.

5. File content storage is abstracted behind `server/src/storage/`. `storage.interface.ts` defines the contract, `local-disk.ts` and `s3-storage.ts` provide the concrete implementations, and `factory.ts` chooses between them. This is the key persistence boundary for the actual file bytes.

6. Metadata or application state is separated from blob storage through `server/src/db/index.ts`. That suggests a distinct database layer for records such as file info, expiry timestamps, or access-related state, while large file payloads go to disk or S3.

7. Redis is used as a supporting infrastructure component through `server/src/lib/redis.ts`. Combined with `services/rate-limit.ts`, it likely backs request throttling and other short-lived coordination/state needed by the API.

8. Cleanup is handled as its own flow rather than being embedded in request handling. `server/src/queues/cleanup.ts` and `server/src/services/cleanup.ts` indicate asynchronous deletion or retirement of expired files, with `services/expiry.ts` deciding when records become eligible for cleanup.

9. The end-to-end data flow is: incoming request → validation and rate limiting → optional password checks → metadata persistence in the DB layer → file write to the selected storage backend → later expiry/cleanup job → deletion from storage and database. That separation is the core architectural pattern in this repo.

10. The design supports multiple deployment modes. Local disk storage is present for development or simple setups, while S3 storage and Redis imply production-oriented external dependencies.

11. Testing is narrow and focused in this snapshot. `server/tests/password.test.ts` covers the password service, and the generated JS/typings are checked in alongside the TypeScript test source.

12. The `dropifi-v1/` directory mirrors an older, simpler shape with its own `server.ts` and `cleanup.ts`. It appears to represent the previous generation of the same service and should not be diagrammed as a runtime dependency of v2.

Main entry points: [`server/src/server.ts`](https://github.com/thesynthax/dropifi/blob/main/server/src/server.ts) (Server), [`server/src/services/cleanup.ts`](https://github.com/thesynthax/dropifi/blob/main/server/src/services/cleanup.ts) (Cleanup), [`server/src/storage/factory.ts`](https://github.com/thesynthax/dropifi/blob/main/server/src/storage/factory.ts) (Storage factory), [`server/src/db/index.ts`](https://github.com/thesynthax/dropifi/blob/main/server/src/db/index.ts) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_active["Dropifi v2"]
  node_server_src_server_ts["Server<br/>entrypoint<br/>[server.ts]"]
  node_server_config_config_json["Config<br/>[config.json]"]
  node_server_src_services_validation_ts["Validation<br/>request checks<br/>[validation.ts]"]
  node_server_src_services_rate_limit_ts["Rate limit<br/>throttling<br/>[rate-limit.ts]"]
  node_server_src_services_password_ts["Password<br/>access control<br/>[password.ts]"]
  node_server_src_services_expiry_ts["Expiry<br/>lifecycle rules<br/>[expiry.ts]"]
  node_server_src_services_cleanup_ts["Cleanup<br/>retention orchestration<br/>[cleanup.ts]"]
  node_server_src_queues_cleanup_ts["Cleanup queue<br/>async job queue<br/>[cleanup.ts]"]
  node_server_src_db_index_ts[("Database<br/>metadata store<br/>[index.ts]")]
  node_server_src_lib_redis_ts[("Redis<br/>coordination store<br/>[redis.ts]")]
  node_server_src_storage_factory_ts["Storage factory<br/>backend selector<br/>[factory.ts]"]
  node_server_src_storage_local_disk_ts[("Local disk<br/>blob storage<br/>[local-disk.ts]")]
  node_server_src_storage_s3_storage_ts[("S3 storage<br/>blob storage<br/>[s3-storage.ts]")]
end

subgraph group_legacy["Dropifi v1"]
  node_dropifi_v1_src_server_ts["V1 server<br/>legacy entrypoint<br/>[server.ts]"]
  node_dropifi_v1_src_cleanup_ts["V1 cleanup<br/>legacy job<br/>[cleanup.ts]"]
end

node_server_src_server_ts -->|"loads"| node_server_config_config_json
node_server_src_server_ts -->|"uses"| node_server_src_services_validation_ts
node_server_src_server_ts -->|"uses"| node_server_src_services_rate_limit_ts
node_server_src_server_ts -->|"uses"| node_server_src_services_password_ts
node_server_src_server_ts -->|"uses"| node_server_src_db_index_ts
node_server_src_server_ts -->|"uses"| node_server_src_storage_factory_ts
node_server_src_server_ts -->|"uses"| node_server_src_lib_redis_ts
node_server_src_server_ts -->|"starts"| node_server_src_queues_cleanup_ts
node_server_src_services_rate_limit_ts -->|"backed by"| node_server_src_lib_redis_ts
node_server_src_services_expiry_ts -->|"triggers"| node_server_src_services_cleanup_ts
node_server_src_services_cleanup_ts -->|"deletes"| node_server_src_db_index_ts
node_server_src_services_cleanup_ts -->|"deletes"| node_server_src_storage_factory_ts
node_server_src_queues_cleanup_ts -->|"runs"| node_server_src_services_cleanup_ts
node_server_src_storage_factory_ts -->|"selects"| node_server_src_storage_local_disk_ts
node_server_src_storage_factory_ts -->|"selects"| node_server_src_storage_s3_storage_ts
node_server_src_services_password_ts -->|"checks"| node_server_src_db_index_ts
node_dropifi_v1_src_server_ts -.->|"paired with"| node_dropifi_v1_src_cleanup_ts

click node_server_src_server_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/server.ts"
click node_server_config_config_json "https://github.com/thesynthax/dropifi/blob/main/server/config/config.json"
click node_server_src_services_validation_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/services/validation.ts"
click node_server_src_services_rate_limit_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/services/rate-limit.ts"
click node_server_src_services_password_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/services/password.ts"
click node_server_src_services_expiry_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/services/expiry.ts"
click node_server_src_services_cleanup_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/services/cleanup.ts"
click node_server_src_queues_cleanup_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/queues/cleanup.ts"
click node_server_src_db_index_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/db/index.ts"
click node_server_src_lib_redis_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/lib/redis.ts"
click node_server_src_storage_factory_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/storage/factory.ts"
click node_server_src_storage_local_disk_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/storage/local-disk.ts"
click node_server_src_storage_s3_storage_ts "https://github.com/thesynthax/dropifi/blob/main/server/src/storage/s3-storage.ts"
click node_dropifi_v1_src_server_ts "https://github.com/thesynthax/dropifi/blob/main/dropifi-v1/src/server.ts"
click node_dropifi_v1_src_cleanup_ts "https://github.com/thesynthax/dropifi/blob/main/dropifi-v1/src/cleanup.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_server_src_server_ts,node_server_config_config_json,node_server_src_services_validation_ts,node_server_src_services_rate_limit_ts,node_server_src_services_password_ts,node_server_src_services_expiry_ts,node_server_src_services_cleanup_ts,node_server_src_queues_cleanup_ts,node_server_src_db_index_ts,node_server_src_lib_redis_ts,node_server_src_storage_factory_ts,node_server_src_storage_local_disk_ts,node_server_src_storage_s3_storage_ts toneBlue
class node_dropifi_v1_src_server_ts,node_dropifi_v1_src_cleanup_ts toneAmber
```

## Components

### Dropifi v2

Current backend file-sharing system in server/

- [Server](https://github.com/thesynthax/dropifi/blob/main/server/src/server.ts): entrypoint · Boots HTTP server and wires the application · `server/src/server.ts`
- [Config](https://github.com/thesynthax/dropifi/blob/main/server/config/config.json): runtime config · Central deployment configuration · `server/config/config.json`
- [Validation](https://github.com/thesynthax/dropifi/blob/main/server/src/services/validation.ts): request checks · Validates incoming requests and payloads · `server/src/services/validation.ts`
- [Rate limit](https://github.com/thesynthax/dropifi/blob/main/server/src/services/rate-limit.ts): throttling · Controls request volume and short-lived abuse protection · `server/src/services/rate-limit.ts`
- [Password](https://github.com/thesynthax/dropifi/blob/main/server/src/services/password.ts): access control · Handles password protection and verification · `server/src/services/password.ts`
- [Expiry](https://github.com/thesynthax/dropifi/blob/main/server/src/services/expiry.ts): lifecycle rules · Determines when files become eligible for retirement · `server/src/services/expiry.ts`
- [Cleanup](https://github.com/thesynthax/dropifi/blob/main/server/src/services/cleanup.ts): retention orchestration · Coordinates deletion of expired files and records · `server/src/services/cleanup.ts`
- [Cleanup queue](https://github.com/thesynthax/dropifi/blob/main/server/src/queues/cleanup.ts): async job queue · Runs deferred cleanup work · `server/src/queues/cleanup.ts`
- [Database](https://github.com/thesynthax/dropifi/blob/main/server/src/db/index.ts): metadata store · Persists file records and application state · `server/src/db/index.ts`
- [Redis](https://github.com/thesynthax/dropifi/blob/main/server/src/lib/redis.ts): coordination store · Supports throttling and short-lived coordination · `server/src/lib/redis.ts`
- [Storage factory](https://github.com/thesynthax/dropifi/blob/main/server/src/storage/factory.ts): backend selector · Chooses the active blob storage implementation · `server/src/storage/factory.ts`
- [Local disk](https://github.com/thesynthax/dropifi/blob/main/server/src/storage/local-disk.ts): blob storage · Local file storage for simple deployments · `server/src/storage/local-disk.ts`
- [S3 storage](https://github.com/thesynthax/dropifi/blob/main/server/src/storage/s3-storage.ts): blob storage · Object storage backend for production deployments · `server/src/storage/s3-storage.ts`

### Dropifi v1

Historical snapshot kept for context

- [V1 server](https://github.com/thesynthax/dropifi/blob/main/dropifi-v1/src/server.ts): legacy entrypoint · Older server generation kept as historical context · `dropifi-v1/src/server.ts`
- [V1 cleanup](https://github.com/thesynthax/dropifi/blob/main/dropifi-v1/src/cleanup.ts): legacy job · Earlier cleanup flow from the legacy snapshot · `dropifi-v1/src/cleanup.ts`

## Connections

- Server → Config: loads · Reads startup configuration
- Server → Validation: uses · Validates requests before handling
- Server → Rate limit: uses · Applies request throttling
- Server → Password: uses · Checks protected uploads and access
- Server → Database: uses · Stores and reads file metadata
- Server → Storage factory: uses · Selects blob storage backend
- Server → Redis: uses · Relies on Redis-backed coordination
- Server → Cleanup queue: starts · Wires asynchronous cleanup processing
- Rate limit → Redis: backed by · Uses Redis for throttling state
- Expiry → Cleanup: triggers · Marks records eligible for retirement
- Cleanup → Database: deletes · Removes expired metadata records
- Cleanup → Storage factory: deletes · Removes stored file content
- Cleanup queue → Cleanup: runs · Executes deferred cleanup jobs
- Storage factory → Local disk: selects · Local storage implementation
- Storage factory → S3 storage: selects · S3 storage implementation
- Password → Database: checks · May verify protected file state against metadata
- V1 server → V1 cleanup: paired with · Legacy runtime and cleanup flow
