Secure Cloud Document Manager — User Guide

1. Welcome

Secure Cloud Document Manager is a private-by-default file storage and sharing platform for a fictional company, Meridian Consulting Group — nested folders, drag-and-drop upload with per-type icons and thumbnails, fine-grained sharing (both folders and individual files) with internal teammates or a revocable public link, a Trash with a 30-day restore window, and per-user storage quotas. This guide walks through the platform exactly as an employee, manager, or admin would use it: the web app first, and the underlying API for anyone integrating or testing programmatically.

2. Two Ways to Use This Platform

There's a real, working web application in front of this platform — you don't need to write any code or run any HTTP requests by hand to try it out.

3. Web App & API Reference

Response envelope

// success
{
  "success": true,
  "data": { /* the actual result */ }
}

// failure
{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "..." }
}

4. Demo Accounts

The demo seeder creates a full Meridian Consulting Group team — one admin, one manager, one employee — so you can try every role immediately. Every account shares the same password:

5. Which Screen Is For Which Role

The web app shows the same core navigation to every signed-in user — what any individual folder or document allows depends on the permission granted on it (§12), not on account role. Role only gates two admin-only screens.

6. Signing In

Via the Web App

1. Open https://demo2.arsiindiainfo.com — you land on the sign-in page.
2. Enter one of the demo emails (§4) and Passw0rd!, or your own account (§7).
3. Tick the reCAPTCHA checkbox.
4. Click Sign in. You land on Browse (§9).

The sign-in page, with a link to create a new account (§7).

Via the API

POST https://demo2.arsiindiainfo.com/api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@meridian.test",
  "password": "Passw0rd!",
  "recaptchaToken": "03AGdBq27..."
}

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "9ba3b6cf3c...",
    "user": { "id": 1, "name": "Ava Admin", "email": "admin@meridian.test", "role": "ADMIN", "status": "ACTIVE" }
  }
}

Copy the accessToken and send it on every subsequent request: Authorization: Bearer eyJhbGciOi...

7. Creating Your Own Account

Anyone can self-register — a new account starts as a Manager with no folders of their own, so creating a root folder (§10) is also its first action.

Via the Web App

1. Click Create one on the sign-in page.
2. Fill in your name, email, and password, and complete the reCAPTCHA.
3. Submit — a verification link is emailed to you. Signing in before clicking it returns 403 EMAIL_NOT_VERIFIED.
4. Click the link (or open /verify-email/:token directly), then sign in (§6).

Creating a new account.

Via the API: POST/auth/register — { name, email, password, recaptchaToken }. POST/auth/verify-email/:token.

8. Your Session & Signing Out

Access tokens are short-lived. The web app quietly exchanges the refreshToken for a new pair whenever a request comes back 401 — you won't see a token expire while using the app.

Via the Web App: click your avatar (top right) → Sign out, or Change password to update your own credentials. Via the API: POST/auth/refresh · POST/auth/logout · PUT/users/me/password.

The avatar menu.

Changing your password signs out every other session.

9. The Browse Page (Home)

Browse is the landing page after sign-in — a welcome banner, live stat cards, your folders as a colorful grid, a Recent Documents table, and a Quick Actions panel.

Browse — the home page.

Via the API: GET/folders/children (no id segment = root) returns your accessible top-level folders; GET/dashboard (§14) backs the stat cards and Recent Documents table.

10. Folders

Via the Web App

1. Click New folder from Browse or from inside any folder you can edit.
2. Click a folder card to open it — Rename and Delete appear on hover; Share is always visible (§12).
3. Deleting moves it (and everything inside it) to Trash (§15) — nothing is gone for good yet.

Creating a folder.

Renaming one.

Inside a folder — breadcrumb navigation, subfolders, and documents.

Via the API

POST/folders — { name, parentFolderId? }. A duplicate name in the same parent returns 409 DUPLICATE_NAME; over the 20-folder quota (§14) returns 409 FOLDER_QUOTA_EXCEEDED. GET/folders/:id/children · PUT/folders/:id · DELETE/folders/:id.

11. Uploading & Viewing Documents

Via the Web App

1. Inside a folder, click Upload or drag files onto the page.
2. Each file shows its type icon while uploading; once processed, a real thumbnail replaces the icon for images and PDFs.
3. Click a document to open its detail panel — Details and Preview tabs, plus Download, Share, Upload new version, and Delete.

Via the API

Upload is a two-step, direct-to-S3 flow — the API server never sees the file bytes:

1. POST/documents/uploads/initiate — { folderId, fileName, mimeType, sizeBytes } returns a presigned PUT URL.
2. Upload the file straight to that URL, then POST/documents/uploads/complete — { folderId, s3Key, name, checksumSha256 } to finalize.

GET/documents/:id/download · GET/documents/:id/preview · GET/documents/:id/thumbnail — each returns a short-lived presigned URL, never the file itself. POST/documents/:id/versions/initiate/complete — upload a new version of an existing document.

12. Sharing — Documents and Folders

Both a folder and an individual document can be shared the same way: invite a teammate by email at Viewer/Editor/Owner, or — for documents only — generate a revocable, expiring public link that needs no account at all.

Via the Web App

1. Click Share on any folder card or document row.
2. Under Invite a person, start typing a name or email — matching teammates appear in a dropdown; click one to fill it in, pick a permission, and click Invite.
3. Documents only: under External link, choose View or Download, an expiry (1 or 7 days), and an optional max-download cap, then click Generate link.
4. Anyone already granted access is listed with a Revoke link next to their name.

The autocomplete suggests teammates as you type.

A document's Share dialog, with a generated external link.

Sharing a folder instead — no External Link section, since public links stay document-only.

Opening a public link with no account at all

A share link opens a standalone page — no app header, no sign-in — showing the file name and size, a Download (or, for View links, an inline preview) button. Revoking it from the Share dialog, or letting it expire or hit its download cap, immediately breaks the link (409 SHARE_LINK_REVOKED / SHARE_LINK_EXPIRED / SHARE_LINK_LIMIT_REACHED).

Via the API

POST/folders/:id/permissions / /documents/:id/permissions — { email, permission }. GET the same path lists current grants; DELETE .../permissions/:userId revokes one. POST/documents/:id/share-links — { permission, expiresInHours, maxDownloads? }. GET/s/:token is the public, unauthenticated resolve — no bearer token, ever.

GET/users/search?q= — the autocomplete's lookup, available to any signed-in user (id/name/email only, never role/status).

13. Searching

Via the Web App: type into the search box in the top bar and press Enter — results show every document you can access, across every folder, with its folder location and size.

Via the API: GET/documents?search=&page=1&limit=20.

14. The Dashboard & Your Quotas

Every quota is checked against your current (non-deleted) state, not a lifetime counter — deleting something frees its slot back up immediately.

The Dashboard — quota bars turn red near the limit.

Via the API: GET/dashboard returns recentDocuments, storageUsedBytes, sharedFolders, and quotas as one payload.

15. Trash — Restore or Delete Forever

Deleting a folder or document moves it to Trash — recoverable for 30 days (§18), after which an automatic job purges it for good.

Via the Web App

1. Open Trash — each row shows how many days remain before automatic purge.
2. Click Restore to bring it back, or Delete permanently to purge it immediately — this is irreversible, and a confirmation dialog says so.

Trash.

Via the API: GET/trash · POST/folders/:id/restore / /documents/:id/restore · DELETE/trash/folders/:id / /trash/documents/:id — permanent, requires it to already be in Trash (409 NOT_IN_TRASH otherwise).

16. Admin: User Management

Sign in as an admin account (§4) to manage the team. These endpoints return 403 FORBIDDEN_ROLE for anyone else.

1. Open Users — click Invite (name, email, role) to add someone directly (no self-registration needed).
2. Change a user's role from the dropdown, or click Disable/Enable to toggle their access.
3. Click Delete to permanently remove an account — this fails with 409 USER_HAS_CONTENT if they still own folders or documents that exist.

Admin: User management.

Via the API: POST/users · GET/users · PUT/users/:id — { role?, status? } · DELETE/users/:id — blocked for your own account, and for one protected super-admin account.

17. Admin: Audit Log

Every sensitive action — a folder created, a permission granted, a user invited, a file permanently deleted — is written to an append-only trail, automatically pruned after 3 months (§18).

Admin: Audit Log — click a row to expand its details.

Via the API: GET/audit-logs.

18. Storage Lifecycle & Automatic Cleanup

Two scheduled jobs run against this deployment without any user action:

None of this needs a click — it runs on a schedule server-side (php spark cleanup:old-files / cleanup:audit-logs).

19. Error Responses

20. Full Endpoint Reference

All paths are relative to https://demo2.arsiindiainfo.com/api/v1.

21. FAQ & Troubleshooting

The reCAPTCHA checkbox won't check, or my login is rejected

Make sure third-party content isn't blocked by a privacy extension — the widget loads a script from google.com. If the checkbox works but submission still fails, the token likely expired (about two minutes); the form resets it automatically — just complete it again.

I uploaded a file and it still shows a generic icon, not a thumbnail

Thumbnails are generated asynchronously after upload — give it a few seconds and refresh. Only images and PDFs get a real thumbnail; everything else always shows its type icon by design.

I deleted a folder — is everything inside it gone?

No — deleting a folder moves it and everything inside it to Trash (§15) together, recoverable as a whole for 30 days. Nothing is actually removed until you purge it, or the automatic 30-day job does (§18).

Why did my file disappear even though I never deleted it?

The 30-day old-file cleanup job (§18) keeps only the latest 5 versions of files older than 30 days and removes the rest — you'd have received a notification when it happened. The current version is never touched.

I opened a shared link and it says it's invalid — was it ever valid?

By design this platform doesn't distinguish "expired" from "revoked" from "never existed" in most contexts (§5's guardrail) — but share links are the one exception, returning a specific reason (SHARE_LINK_EXPIRED/REVOKED/LIMIT_REACHED) since there's no ownership-privacy concern on a link someone already had.

Where do I see the full request/response schema for every field?

The interactive Swagger UI at /api/docs documents every field, validation rule, and example — it's disabled on the public demo, so run the project locally (see the repo's README) to browse it.

Need more detail? This guide covers the day-to-day workflows. Schema, stored procedures, and security architecture are documented separately in the project's docs/ folder and its README.

© 2026 Arsi India Info. All rights reserved.

Secure Cloud Document Manager — a portfolio build modeled on Meridian Consulting Group.
Source code licensed under MIT · name & logo protected under TRADEMARK.md
arsiindiainfo.com