# dan1el-19/chmura-blokserwis architecture

> Architecture diagram of the GitHub repository dan1el-19/chmura-blokserwis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dan1el-19/chmura-blokserwis
- Repository: https://github.com/dan1el-19/chmura-blokserwis

## Overview

##### Project type and purpose
- This is a full-stack, cloud-native file-management web platform built with Next.js (App Router) for the frontend and serverless API routes for the backend.
- It uses Firebase Authentication for identity, Cloudflare R2 for object storage (S3-compatible), and role-based access control (basic, plus, admin).

##### Main architectural components
a. Client (Web / PWA)
- Next.js React pages & components (src/app, src/components)
- Service Worker (public/sw.js), PWA manifest (public/manifest.json)
b. Next.js Serverless Layer
- UI rendering: SSR/SSG via Next.js App Router
- API Routes (src/app/api/*) handling file operations, user profile, admin endpoints
- Middleware (src/middleware.ts) for auth checks, rate limiting
c. Authentication & Authorization
- Firebase Authentication (Google, email/password)
- JWT validation on each API route via Firebase Admin SDK (src/lib/firebaseAdmin.ts)
- Role enforcement in API handlers
d. Object Storage
- Cloudflare R2 bucket (via AWS-S3 compatible SDK in src/lib/storage.ts)
- Multipart upload workflow (src/lib/multipartUpload*, scripts/*.mjs)
e. Data & Logging
- Activity logs (could be stored in R2 or Firebase/Firestore – adjust if needed)
- Storage and usage statistics gathered by API
f. Admin Panel
- Next.js pages under src/app/admin-panel for user management and logs
- Admin API under src/app/api/admin/*

##### Relationships & interactions
1. User (Browser) → Next.js UI
- Navigates to login, storage, file preview, admin pages
2. UI ↔ Next.js Serverless API
- API calls: /api/auth/*, /api/files/*, /api/user/profile, /api/admin/*
- Requests carry Firebase JWT in headers
3. API → Firebase Auth
- Validates incoming JWT, resolves user identity & role
4. API → Cloudflare R2
- Executes file operations (upload, download, delete, presign URLs)
- Manages multipart uploads and bucket operations
5. API → (Optional) Logging/Analytics store
- Persistence of usage stats, upload analytics, queue logs
6. Admin API → User DB / Logs
- CRUD operations on users, password resets, roles

##### Architectural patterns & principles
- Serverless API per feature (each route in its own folder)
- Separation of concerns: UI vs API vs storage vs auth
- Role-based access control enforced at the API edge
- Modular lib layer for cross-cutting concerns (auth, storage, notifications, rate-limit)
- Scripts folder for maintenance tasks (e.g., abort-multipart, set-admin)

##### Essential details to capture
- All API route groups and their domain responsibilities
- The multipart upload workflow (scripts + lib) interacting with R2
- Middleware/pass-through for JWT & RBAC
- PWA features (offline.html, sw.js) connecting back to API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        NextApp["Next.js App Router\n(src/app/)"]:::ui
        Components["React UI Components\n(src/components/)"]:::ui
        SW["Service Worker\n(public/sw.js)"]:::ui
        Manifest["PWA Manifest\n(public/manifest.json)"]:::ui
        Offline["Offline Fallback\n(public/offline.html)"]:::ui
    end

    %% Admin Panel UI
    subgraph "Admin Panel UI"
        direction TB
        AdminUI["Admin Dashboard UI\n(src/app/admin-panel/page.tsx)"]:::ui
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        APIGW["Next.js Serverless API\n(src/app/api/*)"]:::api
        Middleware["Middleware\n(src/middleware.ts)"]:::api
        AuthLib["Auth Helpers\n(src/lib/firebaseAdmin.ts\nsrc/lib/auth.ts)"]:::api
        StorageLib["Storage Wrapper\n(src/lib/storage.ts)"]:::api
        Multipart["Multipart Upload Logic\n(src/lib/multipartUpload.ts\nsrc/lib/multipartUploadWorkflow.ts)"]:::api
        Notifications["Notifications\n(src/lib/notifications.ts)"]:::api
    end

    %% API Domains
    subgraph "API Domains"
        direction TB
        subgraph "Auth API"
            direction TB
            AuthRoutes["/api/auth/*\n(src/app/api/auth/)"]:::api
        end
        subgraph "File API"
            direction TB
            FilesRoutes["/api/files/*\n(src/app/api/files/)"]:::api
            UploadAnalytics["Upload Analytics\n(src/app/api/files/upload-analytics/route.ts)"]:::api
            QueueLog["Queue Log\n(src/app/api/files/queue-log/route.ts)"]:::api
            StorageStats["Storage Stats\n(src/app/api/files/storage-stats/route.ts)"]:::api
        end
        subgraph "User API"
            direction TB
            UserProfile["User Profile\n(src/app/api/user/profile/route.ts)"]:::api
        end
        subgraph "Admin API"
            direction TB
            AdminUsers["Admin Users\n(src/app/api/admin/users/route.ts)"]:::api
            AdminUsersPwd["Password Reset\n(src/app/api/admin/users/password/route.ts)"]:::api
            AdminUsersUpdate["Role Update\n(src/app/api/admin/users/update/route.ts)"]:::api
            AdminMainStorage["Admin Storage\n(src/app/api/admin/main-storage/route.ts)"]:::api
        end
        SystemStats["System Stats\n(src/app/api/system/stats/route.ts)"]:::api
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        FirebaseAuth["Firebase Authentication"]:::ext
        CloudflareR2["Cloudflare R2"]:::ext
        LogsDB["Logs / Analytics Store"]:::sto
        CI["CI/CD (Vercel/Firebase)"]:::infra
    end

    %% Connections
    NextApp -->|renders & calls| APIGW
    Components -->|renders UI| NextApp
    SW -->|intercepts requests| APIGW
    Manifest -->|provides PWA config| NextApp
    Offline -->|fallback content| SW

    AdminUI -->|calls APIs| APIGW

    APIGW -->|passes through| Middleware
    Middleware -->|auth & rate-limit| FirebaseAuth
    APIGW -->|uses| AuthRoutes
    APIGW -->|uses| FilesRoutes
    APIGW -->|uses| UserProfile
    APIGW -->|uses| AdminUsers
    APIGW -->|uses| AdminUsersPwd
    APIGW -->|uses| AdminUsersUpdate
    APIGW -->|uses| AdminMainStorage
    APIGW -->|uses| SystemStats

    AuthRoutes -->|validate JWT| AuthLib
    UserProfile -->|validate JWT| AuthLib
    AuthLib -->|verify token| FirebaseAuth

    FilesRoutes -->|file operations| StorageLib
    StorageLib -->|manage multipart| Multipart
    Multipart -->|upload parts| CloudflareR2
    StorageLib -->|object ops| CloudflareR2

    FilesRoutes -->|log upload analytics| UploadAnalytics
    FilesRoutes -->|log queue events| QueueLog
    FilesRoutes -->|gather storage stats| StorageStats

    UploadAnalytics -->|store logs| LogsDB
    QueueLog -->|store logs| LogsDB
    StorageStats -->|store stats| LogsDB
    Notifications -->|send events| LogsDB

    CI -->|deploys| NextApp
    CI -->|deploys| APIGW

    %% Click Events
    click NextApp "https://github.com/dan1el-19/chmura-blokserwis/tree/main/src/app/"
    click Components "https://github.com/dan1el-19/chmura-blokserwis/tree/main/src/components/"
    click SW "https://github.com/dan1el-19/chmura-blokserwis/blob/main/public/sw.js"
    click Manifest "https://github.com/dan1el-19/chmura-blokserwis/blob/main/public/manifest.json"
    click Offline "https://github.com/dan1el-19/chmura-blokserwis/blob/main/public/offline.html"
    click Middleware "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/middleware.ts"
    click AuthLib "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/lib/firebaseAdmin.ts"
    click AuthLib "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/lib/auth.ts"
    click StorageLib "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/lib/storage.ts"
    click Multipart "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/lib/multipartUpload.ts"
    click Multipart "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/lib/multipartUploadWorkflow.ts"
    click AuthRoutes "https://github.com/dan1el-19/chmura-blokserwis/tree/main/src/app/api/auth/"
    click FilesRoutes "https://github.com/dan1el-19/chmura-blokserwis/tree/main/src/app/api/files/"
    click UserProfile "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/user/profile/route.ts"
    click AdminUsers "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/admin/users/route.ts"
    click AdminUsersPwd "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/admin/users/password/route.ts"
    click AdminUsersUpdate "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/admin/users/update/route.ts"
    click AdminMainStorage "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/admin/main-storage/route.ts"
    click SystemStats "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/system/stats/route.ts"
    click AdminUI "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/admin-panel/page.tsx"
    click UploadAnalytics "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/files/upload-analytics/route.ts"
    click QueueLog "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/files/queue-log/route.ts"
    click StorageStats "https://github.com/dan1el-19/chmura-blokserwis/blob/main/src/app/api/files/storage-stats/route.ts"
    click CI "https://github.com/dan1el-19/chmura-blokserwis/blob/main/scripts/set-admin.mjs"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef api fill:#d4edda,stroke:#155724,color:#155724;
    classDef ext fill:#fff3cd,stroke:#856404,color:#856404;
    classDef sto fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef infra fill:#f8d7da,stroke:#721c24,color:#721c24;
```
