Introduction: This diagram provides a high-level overview of the entire SwiftVault system, showing the separation of concerns and the hybrid API approach that combines REST and GraphQL for optimal performance and flexibility.
graph TB
subgraph "Client Layer"
UI[Next.js Frontend<br/>TypeScript + Tailwind]
Browser[Browser<br/>HTTP-only Cookies]
end
subgraph "API Gateway"
Router[Next.js App Router<br/>route.ts]
Auth[Auth Middleware<br/>JWT Validation]
end
subgraph "Backend Services"
GoServer[Go Server<br/>Hybrid API]
GraphQL[GraphQL API]
RestAPI[REST API Handlers<br/>Auth, Files, Admin]
FileService[File Service Logic]
AuthService[Auth Service Logic]
AdminService[Admin Service Logic]
HashingService[SHA-256 Hashing]
MimeService[MIME Validation]
end
subgraph "Data Layer"
PostgreSQL[(PostgreSQL<br/>User & File Metadata)]
Redis[(Redis<br/>Cache & Rate Limiting)]
MinIO[(MinIO<br/>Object Storage)]
end
subgraph "External Services"
Resend[Resend<br/>Email Service]
end
UI --> Router
Browser --> Router
Router -- public --> GoServer
Router -- protected --> Auth
Auth -- authenticated --> GoServer
GoServer --> GraphQL
GoServer --> RestAPI
RestAPI -- login, register, etc. --> AuthService
RestAPI -- file uploads, etc. --> FileService
GraphQL -- queries, mutations --> FileService
GraphQL -- analytics --> AdminService
FileService --> HashingService
FileService --> MimeService
FileService --> PostgreSQL
FileService --> MinIO
AuthService --> PostgreSQL
AuthService --> Redis
AuthService --> Resend
AdminService --> PostgreSQL
GoServer -.->|Rate Limiting| Redis
GraphQL -.->|Caching| Redis
HashingService --> PostgreSQL
MimeService --> FileService
Introduction: This diagram clarifies how requests are handled based on whether the endpoint is public or protected, showing the different security and rate-limiting measures applied throughout the request lifecycle.
graph LR
subgraph "Client Request"
A[Client Request] --> B[Next.js Router]
end
subgraph "Routing and Security"
B -->|Public Endpoint| P[IP-based Rate Limiter]
B -->|Protected Endpoint| C[Cookie Extraction]
C --> D[Auth Header Addition]
D --> E[JWT Validation]
E --> F[User-based Rate Limiter]
end
subgraph "Backend Processing"
P --> G{Backend Endpoint}
F --> G
G --> H[GraphQL]
G --> I[REST]
end
subgraph "Business Logic"
H --> J[GraphQL Handlers<br/>Search, Filter, etc.]
I --> K[REST Handlers<br/>Upload, Login, etc.]
end
subgraph "Security Layers"
E -.->|Invalid Token| L[Return 401]
P -.->|Limit Exceeded| M[Return 429]
F -.->|Limit Exceeded| M
end
Introduction: This sequence diagram details the authentication flow, highlighting that all authentication steps are handled by dedicated REST endpoints rather than GraphQL, ensuring optimal security and performance for credential-based operations.
sequenceDiagram
participant U as User
participant F as Frontend
participant R as Router
participant B as Backend
participant DB as PostgreSQL
participant Cache as Redis
participant Email as Resend
Note over U,Email: Registration Flow
U->>F: Enter email & password
F->>R: POST /api/register
R->>B: Forward to REST Handler
B->>Cache: Generate & store OTP
B->>Email: Send OTP email
B->>F: OTP sent successfully
U->>F: Enter OTP
F->>R: POST /api/verify-otp
R->>B: Forward to REST Handler
B->>Cache: Verify OTP
Cache->>B: OTP valid
B->>DB: Create user record
B->>B: Generate JWT tokens
B->>F: Return tokens + Set cookies
F->>U: Redirect to dashboard
Note over U,Email: Login Flow
U->>F: Enter credentials
F->>R: POST /api/login
R->>B: Forward to REST Handler
B->>DB: Validate credentials
DB->>B: User validated
B->>B: Generate JWT tokens
B->>F: Return tokens + Set cookies
F->>U: Redirect to dashboard
Introduction: This flow demonstrates the file upload process using a dedicated REST endpoint, which is a common and efficient pattern for handling large binary data, featuring MIME validation, SHA-256 deduplication, and optimized storage operations.
sequenceDiagram
participant U as User
participant F as Frontend
participant R as Router
participant B as Backend
participant DB as PostgreSQL
participant S as MinIO
participant Cache as Redis
U->>F: Select files for upload
F->>F: Validate file types
F->>R: POST /api/files/upload
R->>R: Extract JWT from cookies
R->>B: Forward with auth header
B->>B: Validate JWT & extract claims
B->>Cache: Check rate limits
Cache->>B: Rate limit OK
B->>B: Read first 512 bytes
B->>B: Validate MIME type
B->>B: Generate SHA-256 hash
B->>DB: Check if hash exists
alt File is duplicate
DB->>B: Hash found
B->>DB: Create file reference
B->>F: Upload complete (deduplicated)
else New file
DB->>B: Hash not found
B->>S: Store file object
S->>B: Storage confirmed
B->>DB: Create file record
B->>DB: Update user storage
B->>F: Upload complete (new file)
end
F->>U: Show upload success
The SwiftVault architecture employs a hybrid API model that strategically combines REST and GraphQL endpoints based on use case requirements:
| API Type | Use Cases | Benefits |
|---|---|---|
| REST API | Authentication, file operations, administrative tasks | Simple, predictable endpoints, optimal for binary data |
| GraphQL API | Complex queries, search, filtering, analytics | Flexible data retrieval, reduced over-fetching |
- JWT Authentication with HTTP-only cookies
- Dual-rate limiting (IP-based + user-based)
- MIME validation at both frontend and backend levels
- File deduplication via SHA-256 hashing
- Redis caching for frequent queries and rate limiting
- Efficient routing through Next.js App Router
- PostgreSQL for metadata and user management
- MinIO for scalable object storage
- Redis for caching and session management
- Frontend MIME validation for immediate user feedback
- Backend verification for security enforcement
- Multi-layer security checks throughout the pipeline
graph LR
A[Client] --> B[Next.js Router]
B --> C[Authentication]
C --> D[Rate Limiting]
D --> E[API Gateway]
E --> F[REST/GraphQL Routing]
F --> G[Business Logic]
G --> H[Data Layer]
Client Request → Next.js Router handling
Authentication → JWT validation and cookie management
Rate Limiting → IP-based or user-based throttling
API Gateway → REST/GraphQL endpoint routing
Business Logic → File processing, authentication, analytics
Data Layer → Persistent storage operations
✅ Scalability Horizontal scaling capability through microservices design
Separate storage layers for metadata and files
Caching layer for improved performance
Multi-layer authentication and validation
Secure file handling with deduplication
Comprehensive rate limiting
Clear separation of concerns
Hybrid API model for optimal endpoint design
Modular service architecture
Optimized file uploads through REST endpoints
Efficient queries through GraphQL