# rs-labhub/document_management_system architecture

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

- Interactive diagram: https://gitdiagram.com/rs-labhub/document_management_system
- Repository: https://github.com/rs-labhub/document_management_system

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js (App Router) document management system (DMS) with fine-grained authorization powered by Permit.io.
- Users can sign in, browse/create/edit/delete documents based on roles (Admin, Editor, Viewer) and ownership.

##### High-Level Architecture Components
a. Frontend (Browser)
- Next.js React pages & components under `/app` and `/components`.
- shadcn/ui + Tailwind CSS for responsive UI.
- Client-side hooks (`hooks/use-toast.ts`, `hooks/use-mobile.tsx`) and context (`lib/auth-context.tsx`) drive local state, theming, and UI gating (hasPermission).
b. Next.js Server
- **App Router** (server and client components) in `app/*`.
- **Server Actions** (`app/actions.ts`) handle form submissions and calls to business logic (create/update/delete).
- **Middleware** (`middleware.ts`) for authentication, session handling, and request routing.
- **Authorization layer** (`lib/permit.ts`) wrapping Permit.io SDK to check permissions before database operations.
c. Database (Persistence)
- A document store (e.g., PostgreSQL, MongoDB, etc.) accessed from server actions (not shown in file tree but implied).
d. External Service – Permit.io
- Policy Decision Point (PDP) URL and SDK token configured via environment variables.
- Centralized policy management (RBAC + ABAC).
e. Static Assets & CDN
- `/public` folder hosts logo, demo video thumbnail, and other static files.
- Served directly by Next.js or via CDN in production.

##### Component Interactions and Data Flows
1. User opens browser → Next.js Server serves React page with initial data.
2. User performs an action (e.g., “Edit Document”):
- Client calls a server action or API route.
- Server action invokes `checkPermission(userId, action, resourceType, attributes)` → calls Permit.io PDP.
- PDP returns allow/deny → server either proceeds or rejects with error.
- If allowed, server interacts with the database to CRUD the document.
- Response flows back to client; UI updates.
3. Client-side gating: UI components call `hasPermission()` hook (using `lib/auth-context.tsx` + client SDK) to show/hide buttons or links.

##### Architectural Patterns and Design Principles
- **Separation of Concerns**: UI layer (`components/ui/*`), auth logic (`lib/permit.ts`), state/context (`lib/auth-context.tsx`), and server actions (`app/actions.ts`).
- **Externalized Authorization**: All permission checks are delegated to Permit.io, keeping policy definitions out of app code.
- **Server Components vs Client Components**: Next.js App Router structure, with server-rendered pages for secure data fetching, and client components/hooks for interactivity.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef browser fill:#E0F7FA,stroke:#006064,color:#006064
    classDef server fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef data fill:#ECEFF1,stroke:#607D8B,color:#455A64
    classDef external fill:#FFF3E0,stroke:#EF6C00,color:#E65100

    %% Browser Layer
    subgraph "Browser (Client)" 
        direction TB
        HomePage["Home / Dashboard (app/page.tsx)"]:::browser
        LoginPage["Login Page (app/login/page.tsx)"]:::browser
        DocsList["Documents List (app/documents/page.tsx)"]:::browser
        DocDetail["Document Detail (app/documents/[id]/page.tsx)"]:::browser
        NewDoc["New Document (app/documents/new/page.tsx)"]:::browser
        AdminPage["Admin Console (app/admin/page.tsx)"]:::browser
        ThemeProvider["ThemeProvider (components/theme-provider.tsx)"]:::browser
        ModeToggle["ModeToggle (components/mode-toggle.tsx)"]:::browser
        Navbar["Navbar (components/navbar.tsx)"]:::browser
        UseToast["useToast Hook (hooks/use-toast.ts)"]:::browser
        UseMobile["useMobile Hook (hooks/use-mobile.tsx)"]:::browser
        AuthContext["AuthContext & hasPermission (lib/auth-context.tsx)"]:::browser
    end

    %% Server Layer
    subgraph "Next.js Server" 
        direction TB
        Layout["Global Layout (app/layout.tsx)"]:::server
        GlobalsCSS["Global Stylesheet (app/globals.css)"]:::server
        Middleware["Middleware (middleware.ts)"]:::server
        Actions["Server Actions (app/actions.ts)"]:::server
        PermitLayer["Authorization Layer (lib/permit.ts)"]:::server
    end

    %% Data Layer
    subgraph "Database (Persistence)"
        direction TB
        DB["Document Store (PostgreSQL/MongoDB)"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PermitIO["Permit.io PDP Service\n(env: PERMIT_PDP_URL, PERMIT_SDK_TOKEN)"]:::external
        StaticAssets["Static Assets / CDN (public/)"]:::external
    end

    %% Connections
    HomePage -->|"GET /"| Layout
    LoginPage -->|"GET /login"| Middleware
    DocsList -->|"GET /documents"| Layout
    DocDetail -->|"GET /documents/:id"| Layout
    NewDoc -->|"GET /documents/new"| Layout
    AdminPage -->|"GET /admin"| Layout

    ThemeProvider --> AuthContext
    ModeToggle --> AuthContext
    Navbar --> AuthContext
    UseToast --> AuthContext
    UseMobile --> AuthContext

    Layout --> GlobalsCSS
    Layout --> Middleware
    Middleware --> Actions
    Actions --> PermitLayer
    Actions --> DB
    PermitLayer -->|"checkPermission()"| PermitIO

    HomePage --> StaticAssets
    LoginPage --> StaticAssets
    DocsList --> StaticAssets
    DocDetail --> StaticAssets
    NewDoc --> StaticAssets
    AdminPage --> StaticAssets

    AuthContext -->|"hasPermission()"| PermitLayer

    %% Click Events
    click HomePage "https://github.com/rs-labhub/document_management_system/blob/main/app/page.tsx"
    click LoginPage "https://github.com/rs-labhub/document_management_system/blob/main/app/login/page.tsx"
    click DocsList "https://github.com/rs-labhub/document_management_system/blob/main/app/documents/page.tsx"
    click DocDetail "https://github.com/rs-labhub/document_management_system/blob/main/app/documents/[id]/page.tsx"
    click NewDoc "https://github.com/rs-labhub/document_management_system/blob/main/app/documents/new/page.tsx"
    click AdminPage "https://github.com/rs-labhub/document_management_system/blob/main/app/admin/page.tsx"
    click Layout "https://github.com/rs-labhub/document_management_system/blob/main/app/layout.tsx"
    click GlobalsCSS "https://github.com/rs-labhub/document_management_system/blob/main/app/globals.css"
    click ThemeProvider "https://github.com/rs-labhub/document_management_system/blob/main/components/theme-provider.tsx"
    click ModeToggle "https://github.com/rs-labhub/document_management_system/blob/main/components/mode-toggle.tsx"
    click Navbar "https://github.com/rs-labhub/document_management_system/blob/main/components/navbar.tsx"
    click UseToast "https://github.com/rs-labhub/document_management_system/blob/main/hooks/use-toast.ts"
    click UseMobile "https://github.com/rs-labhub/document_management_system/blob/main/hooks/use-mobile.tsx"
    click AuthContext "https://github.com/rs-labhub/document_management_system/blob/main/lib/auth-context.tsx"
    click PermitLayer "https://github.com/rs-labhub/document_management_system/blob/main/lib/permit.ts"
    click Actions "https://github.com/rs-labhub/document_management_system/blob/main/app/actions.ts"
    click Middleware "https://github.com/rs-labhub/document_management_system/blob/main/middleware.ts"
    click StaticAssets "https://github.com/rs-labhub/document_management_system/tree/main/public/"

    %% Legend
    class HomePage,LoginPage,DocsList,DocDetail,NewDoc,AdminPage,ThemeProvider,ModeToggle,Navbar,UseToast,UseMobile,AuthContext browser
    class Layout,GlobalsCSS,Middleware,Actions,PermitLayer server
    class DB data
    class PermitIO,StaticAssets external
```
