Portfolio Build · Public GitHub Demo

Cloud Document Management System

A Dropbox/Drive-style secure business document vault — folders, versioned uploads, internal sharing, expiring external links, full-text-free metadata search, and a complete audit trail — built with React, PHP CodeIgniter 4, MySQL and AWS, with every document byte kept behind a private S3 bucket and backend-issued signed URLs.

Repository

secure-cloud-document-manager

Author

R.M. — Arsi India Info

Category

PHP · AWS S3 · File Security · REST API

License

MIT (code) + Trademark Notice (brand)

1. Executive Summary

The platform lets a business — modeled here as the fictional Meridian Consulting Group — store, organize, version and share its documents (client contracts, invoices, HR letters, compliance policies) the way Dropbox or Google Drive would, except every byte lives in a private S3 bucket that is never reachable directly. Every upload, download, preview and share is authorized first, then served through a short-lived, backend-generated signed URL. This is deliberately the centerpiece of the project: it proves the candidate understands that "storing files in S3" and "storing files in S3 securely" are two different skills.

Scope is deliberately narrow where breadth would add no portfolio value: one storage backend (S3, no multi-cloud abstraction), metadata/name search only (no OCR or full-text content indexing), a stub virus-scan step (logs a result, does not integrate a real scanning engine), and synthetic seed documents for one fictional company — never real business documents, real credentials, or a publicly reachable bucket.

2. Why This Is a Top-Tier Portfolio Project

Document-upload demos are common; a document system that treats authorization as a first-class, per-file concern is not. This project is chosen because it forces decisions a reviewer will recognize as production-grade:

3. Technology Stack

4. Repository & Folder Structure

secure-cloud-document-manager/
├── backend/                              # CodeIgniter 4 (already scaffolded)
│   ├── app/
│   │   ├── Config/                       # Routes.php, Filters.php, Database.php, Aws.php (new), Validation.php
│   │   ├── Controllers/                  # thin: validate via rule group, delegate to Services, return envelope
│   │   │   ├── AuthController.php
│   │   │   ├── UsersController.php
│   │   │   ├── FoldersController.php
│   │   │   ├── DocumentsController.php
│   │   │   ├── SharingController.php
│   │   │   ├── PublicShareController.php     # unauthenticated share-link landing endpoint
│   │   │   ├── AuditLogController.php
│   │   │   └── ProcessingCallbackController.php  # internal, HMAC-signed, called by the Lambda worker
│   │   ├── Services/                     # business rules + authorization; the only callers of Models/SPs
│   │   │   ├── AuthService.php
│   │   │   ├── FolderService.php
│   │   │   ├── DocumentService.php
│   │   │   ├── SharingService.php
│   │   │   └── AuditService.php
│   │   ├── Models/                       # thin wrappers around `CALL sp_xxx(...)` + simple query-builder reads
│   │   ├── Entities/                     # User, Folder, Document, DocumentVersion, ShareLink (typed CI4 Entities)
│   │   ├── Libraries/                    # S3Service (presign put/get), JwtService, HmacSignatureVerifier
│   │   ├── Filters/                      # JwtAuthFilter, RoleFilter, RateLimitFilter, InternalHmacFilter
│   │   ├── Exceptions/                   # ApiException base + typed subclasses carrying httpStatus + errorCode
│   │   └── Database/
│   │       ├── Migrations/               # one class per table, §7
│   │       ├── Seeds/                    # DemoSeeder — Meridian Consulting Group synthetic data
│   │       └── Procedures/                   # raw .sql files for every CREATE PROCEDURE, §8 — run by a migration
│   └── tests/
│       ├── unit/                         # Service-layer unit tests
│       └── api/                          # CIUnitTestCase + FeatureTestTrait, one file per controller
│
├── frontend/                             # React + TypeScript + Vite (already scaffolded)
│   └── src/
│       ├── app/                          # router, providers, layout shell
│       ├── features/
│       │   ├── auth/
│       │   ├── browser/                  # folder tree + document grid/list — the main workspace
│       │   ├── documents/                # detail/preview panel, versions tab, sharing tab, activity tab
│       │   ├── trash/
│       │   ├── audit/
│       │   └── users/
│       ├── components/                   # Breadcrumbs, UploadDropzone, FilePreview, DataTable, ConfirmDialog...
│       ├── lib/                          # apiClient, queryClient, direct-to-S3 uploader helper
│       └── types/
│
├── shared/                               # constants shared by both layers (permission enum, error codes)
├── infrastructure/                       # deployment-related, kept out of application code (already present)
│   ├── docker/                           # Dockerfile.api, Dockerfile.web
│   ├── docker-compose.yml
│   ├── aws/                              # Terraform/CDK: S3 buckets + policies, CloudFront, IAM roles, Lambda
│   └── github-actions/
│
├── docs/                                 # see §32 (already present, empty scaffold)
├── LICENSE                               # MIT (already present)
├── TRADEMARK.md                          # Arsi India Info name/logo notice — see §31
└── README.md                             # already present — expanded per §32

5. Coding Standards & Conventions

6. Roles & Document/Folder Permissions

Authorization is two layers, matching how a real document-management product actually works — a global role for admin-type capabilities, and a per-resource ACL for "who can see this specific file."

6.1 Global roles

6.2 Per-resource permission (sharing)

6.3 How access is resolved

1. The uploader of a document (or creator of a folder) is granted OWNER automatically.
2. A permission granted on a folder is inherited by every document inside it unless a more specific grant exists directly on the document (folder grant is the floor, not a ceiling).
3. ADMIN bypasses ACL checks entirely (needed for the audit/records-management use case) — every such bypass is itself written to the audit log (§11) so the bypass is never invisible.
4. Every Controller action that touches a document or folder calls DocumentService::authorize($user, $document, $requiredPermission) — there is exactly one code path that can grant access, so a missing check can't silently exist in one endpoint but not another.

7. Database Schema (MySQL)

7.1 Table inventory

7.2 Full DDL (abbreviated to essential columns)

CREATE TABLE users (
  id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name            VARCHAR(120)     NOT NULL,
  email           VARCHAR(190)     NOT NULL,
  password_hash   VARCHAR(255)     NOT NULL,
  role            ENUM('ADMIN','MANAGER','EMPLOYEE') NOT NULL DEFAULT 'EMPLOYEE',
  status          ENUM('ACTIVE','DISABLED') NOT NULL DEFAULT 'ACTIVE',
  created_at      DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at      DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted_at      DATETIME         NULL,
  UNIQUE KEY uq_users_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE folders (
  id                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  parent_folder_id  BIGINT UNSIGNED NULL,
  name              VARCHAR(180)     NOT NULL,
  created_by        BIGINT UNSIGNED NOT NULL,
  created_at        DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at        DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted_at        DATETIME         NULL,
  CONSTRAINT fk_folders_parent FOREIGN KEY (parent_folder_id) REFERENCES folders(id) ON DELETE RESTRICT,
  CONSTRAINT fk_folders_creator FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE RESTRICT,
  UNIQUE KEY uq_folder_sibling_name (parent_folder_id, name),
  KEY idx_folders_parent (parent_folder_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE documents (
  id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  folder_id       BIGINT UNSIGNED NOT NULL,
  name            VARCHAR(200)     NOT NULL,
  description     VARCHAR(500)     NULL,
  tags            VARCHAR(255)     NULL,               -- comma-separated, portfolio-scoped (no tag table)
  current_version INT UNSIGNED    NOT NULL DEFAULT 0,
  created_by      BIGINT UNSIGNED NOT NULL,
  created_at      DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at      DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted_at      DATETIME         NULL,
  CONSTRAINT fk_documents_folder FOREIGN KEY (folder_id) REFERENCES folders(id) ON DELETE RESTRICT,
  CONSTRAINT fk_documents_creator FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE RESTRICT,
  KEY idx_documents_folder (folder_id),
  FULLTEXT KEY ftx_documents_search (name, description, tags)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE document_versions (
  id                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  document_id       BIGINT UNSIGNED NOT NULL,
  version_no        INT UNSIGNED    NOT NULL,
  s3_bucket         VARCHAR(120)     NOT NULL,
  s3_key            VARCHAR(400)     NOT NULL,
  mime_type         VARCHAR(150)     NOT NULL,
  size_bytes        BIGINT UNSIGNED NOT NULL,
  checksum_sha256   CHAR(64)         NOT NULL,
  thumbnail_s3_key  VARCHAR(400)     NULL,             -- filled in by the Lambda pipeline, §9.3
  is_current        TINYINT(1)       NOT NULL DEFAULT 0,
  uploaded_by       BIGINT UNSIGNED NOT NULL,
  uploaded_at       DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT fk_versions_document FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE RESTRICT,
  CONSTRAINT fk_versions_uploader FOREIGN KEY (uploaded_by) REFERENCES users(id) ON DELETE RESTRICT,
  UNIQUE KEY uq_document_version (document_id, version_no),
  KEY idx_versions_document_current (document_id, is_current)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE document_permissions (
  id             BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  folder_id      BIGINT UNSIGNED NULL,
  document_id    BIGINT UNSIGNED NULL,
  user_id        BIGINT UNSIGNED NOT NULL,
  permission     ENUM('VIEWER','EDITOR','OWNER') NOT NULL,
  granted_by     BIGINT UNSIGNED NOT NULL,
  granted_at     DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT ck_permission_target CHECK (
    (folder_id IS NOT NULL AND document_id IS NULL) OR (folder_id IS NULL AND document_id IS NOT NULL)
  ),
  CONSTRAINT fk_perm_folder FOREIGN KEY (folder_id) REFERENCES folders(id) ON DELETE CASCADE,
  CONSTRAINT fk_perm_document FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE,
  CONSTRAINT fk_perm_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  UNIQUE KEY uq_perm_folder_user (folder_id, user_id),
  UNIQUE KEY uq_perm_document_user (document_id, user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE share_links (
  id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  document_id     BIGINT UNSIGNED NOT NULL,
  token           CHAR(43)         NOT NULL,          -- URL-safe base64 of 32 random bytes
  permission      ENUM('VIEW','DOWNLOAD') NOT NULL DEFAULT 'DOWNLOAD',
  max_downloads   INT UNSIGNED    NULL,
  download_count  INT UNSIGNED    NOT NULL DEFAULT 0,
  expires_at      DATETIME         NOT NULL,
  revoked_at      DATETIME         NULL,
  created_by      BIGINT UNSIGNED NOT NULL,
  created_at      DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT fk_sharelink_document FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE,
  CONSTRAINT fk_sharelink_creator FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE RESTRICT,
  UNIQUE KEY uq_sharelink_token (token)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE audit_logs (
  id            BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  user_id       BIGINT UNSIGNED NULL,
  action        VARCHAR(60)      NOT NULL,
  entity_type   ENUM('DOCUMENT','FOLDER','USER','SHARE_LINK') NOT NULL,
  entity_id     BIGINT UNSIGNED NOT NULL,
  details       JSON            NULL,
  ip_address    VARCHAR(45)      NULL,
  created_at    DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT fk_audit_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE SET NULL,
  KEY idx_audit_entity (entity_type, entity_id),
  KEY idx_audit_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

document_processing_jobs, refresh_tokens, and trash_retention_settings follow the same conventions (audit columns, InnoDB, utf8mb4) and are included in the migration set under app/Database/Migrations/ — omitted here for brevity since they add no new relational patterns beyond what's shown above.

7.3 Design notes

• Soft delete only at the API/application level (deleted_at); a real S3 object is never deleted by the application — a separate, tightly-scoped scheduled Lambda purges S3 objects for documents past the retention window in trash_retention_settings, so a compromised API credential cannot mass-delete stored files.
• FULLTEXT index on documents(name, description, tags) backs §17 search without introducing Elasticsearch — appropriate for the portfolio's metadata-only search scope (§2).
• All FKs use ON DELETE RESTRICT (except permission grants, which cascade with their parent resource) — nothing in this schema is ever hard-deleted by a cascade the developer didn't explicitly choose.

8. Stored Procedures

Every multi-table or race-sensitive write goes through a stored procedure — this is where transaction boundaries, row locking, and business-rule validation actually live, not scattered across PHP call sites. Every procedure follows the same shape: business-rule failures are raised as SIGNAL SQLSTATE '45000' with a machine-parseable status_code prefix in the message text; unexpected database errors are caught by a DECLARE ... HANDLER FOR SQLEXCEPTION that rolls back and re-signals, so the calling PHP code always gets one of a known set of outcomes.

8.1 Pattern A — validated insert with duplicate check (sp_folder_create)

DELIMITER $$
CREATE PROCEDURE sp_folder_create(
  IN  p_name VARCHAR(180),
  IN  p_parent_folder_id BIGINT UNSIGNED,
  IN  p_created_by BIGINT UNSIGNED,
  OUT p_folder_id BIGINT UNSIGNED,
  OUT p_status_code VARCHAR(30),
  OUT p_message VARCHAR(255)
)
BEGIN
  DECLARE v_parent_exists INT DEFAULT 0;
  DECLARE EXIT HANDLER FOR SQLEXCEPTION
  BEGIN
    ROLLBACK;
    SET p_status_code = 'INTERNAL_ERROR', p_message = 'Unexpected database error while creating folder.';
  END;

  START TRANSACTION;

  IF p_parent_folder_id IS NOT NULL THEN
    SELECT COUNT(*) INTO v_parent_exists FROM folders
      WHERE id = p_parent_folder_id AND deleted_at IS NULL FOR UPDATE;
    IF v_parent_exists = 0 THEN
      ROLLBACK;
      SET p_status_code = 'PARENT_NOT_FOUND', p_message = 'Parent folder does not exist or is deleted.';
      LEAVE sp_folder_create;
    END IF;
  END IF;

  IF EXISTS (
    SELECT 1 FROM folders
    WHERE name = p_name AND deleted_at IS NULL
      AND ((parent_folder_id IS NULL AND p_parent_folder_id IS NULL) OR parent_folder_id = p_parent_folder_id)
  ) THEN
    ROLLBACK;
    SET p_status_code = 'DUPLICATE_NAME', p_message = 'A folder with this name already exists here.';
    LEAVE sp_folder_create;
  END IF;

  INSERT INTO folders (name, parent_folder_id, created_by)
    VALUES (p_name, p_parent_folder_id, p_created_by);
  SET p_folder_id = LAST_INSERT_ID();

  INSERT INTO audit_logs (user_id, action, entity_type, entity_id, details)
    VALUES (p_created_by, 'FOLDER_CREATED', 'FOLDER', p_folder_id, JSON_OBJECT('name', p_name));

  COMMIT;
  SET p_status_code = 'OK', p_message = 'Folder created.';
END$$
DELIMITER ;

8.2 Pattern B — transactional versioning with row locking (sp_document_new_version)

DELIMITER $$
CREATE PROCEDURE sp_document_new_version(
  IN  p_document_id BIGINT UNSIGNED, IN p_s3_bucket VARCHAR(120), IN p_s3_key VARCHAR(400),
  IN  p_mime_type VARCHAR(150), IN p_size_bytes BIGINT UNSIGNED, IN p_checksum CHAR(64), IN p_uploaded_by BIGINT UNSIGNED,
  OUT p_version_id BIGINT UNSIGNED, OUT p_version_no INT UNSIGNED, OUT p_status_code VARCHAR(30), OUT p_message VARCHAR(255)
)
BEGIN
  DECLARE v_deleted_at DATETIME;
  DECLARE EXIT HANDLER FOR SQLEXCEPTION
  BEGIN ROLLBACK; SET p_status_code = 'INTERNAL_ERROR', p_message = 'Unexpected database error while adding version.'; END;

  START TRANSACTION;

  -- lock the parent row so two concurrent uploads can never both compute the same next version_no
  SELECT deleted_at INTO v_deleted_at FROM documents WHERE id = p_document_id FOR UPDATE;
  IF v_deleted_at IS NOT NULL THEN
    ROLLBACK; SET p_status_code = 'DOCUMENT_DELETED', p_message = 'Cannot version a deleted document.'; LEAVE sp_document_new_version;
  END IF;

  UPDATE document_versions SET is_current = 0 WHERE document_id = p_document_id AND is_current = 1;

  SELECT COALESCE(MAX(version_no), 0) + 1 INTO p_version_no FROM document_versions WHERE document_id = p_document_id;

  INSERT INTO document_versions (document_id, version_no, s3_bucket, s3_key, mime_type, size_bytes, checksum_sha256, is_current, uploaded_by)
    VALUES (p_document_id, p_version_no, p_s3_bucket, p_s3_key, p_mime_type, p_size_bytes, p_checksum, 1, p_uploaded_by);
  SET p_version_id = LAST_INSERT_ID();

  UPDATE documents SET current_version = p_version_no WHERE id = p_document_id;

  INSERT INTO document_processing_jobs (document_version_id, status) VALUES (p_version_id, 'PENDING');
  INSERT INTO audit_logs (user_id, action, entity_type, entity_id, details)
    VALUES (p_uploaded_by, 'DOCUMENT_VERSION_UPLOADED', 'DOCUMENT', p_document_id, JSON_OBJECT('versionNo', p_version_no));

  COMMIT;
  SET p_status_code = 'OK', p_message = 'Version uploaded.';
END$$
DELIMITER ;

8.3 Pattern C — validate-and-consume with branching outcomes (sp_share_link_consume)

DELIMITER $$
CREATE PROCEDURE sp_share_link_consume(
  IN  p_token CHAR(43),
  OUT p_document_id BIGINT UNSIGNED, OUT p_permission VARCHAR(10),
  OUT p_status_code VARCHAR(30), OUT p_message VARCHAR(255)
)
BEGIN
  DECLARE v_expires_at DATETIME; DECLARE v_revoked_at DATETIME;
  DECLARE v_max INT UNSIGNED; DECLARE v_count INT UNSIGNED; DECLARE v_found INT DEFAULT 0;
  DECLARE EXIT HANDLER FOR SQLEXCEPTION
  BEGIN ROLLBACK; SET p_status_code = 'INTERNAL_ERROR', p_message = 'Unexpected database error while resolving link.'; END;

  START TRANSACTION;
  SELECT COUNT(*) INTO v_found FROM share_links WHERE token = p_token FOR UPDATE;
  IF v_found = 0 THEN
    ROLLBACK; SET p_status_code = 'NOT_FOUND', p_message = 'This link is invalid.'; LEAVE sp_share_link_consume;
  END IF;

  SELECT document_id, permission, expires_at, revoked_at, max_downloads, download_count
    INTO p_document_id, p_permission, v_expires_at, v_revoked_at, v_max, v_count
    FROM share_links WHERE token = p_token;

  IF v_revoked_at IS NOT NULL THEN
    ROLLBACK; SET p_status_code = 'REVOKED', p_message = 'This link has been revoked.'; LEAVE sp_share_link_consume;
  ELSEIF v_expires_at < NOW() THEN
    ROLLBACK; SET p_status_code = 'EXPIRED', p_message = 'This link has expired.'; LEAVE sp_share_link_consume;
  ELSEIF v_max IS NOT NULL AND v_count >= v_max THEN
    ROLLBACK; SET p_status_code = 'LIMIT_REACHED', p_message = 'This link has reached its download limit.'; LEAVE sp_share_link_consume;
  END IF;

  UPDATE share_links SET download_count = download_count + 1 WHERE token = p_token;
  COMMIT;
  SET p_status_code = 'OK', p_message = 'Link valid.';
END$$
DELIMITER ;

8.4 Full procedure index

Every procedure is called from its Model through CodeIgniter's Query Builder::query() with bound parameters (never interpolated), and every OUT parameter is read back via a second SELECT @p_status_code, @p_message — the Model translates a non-OK status code into the matching typed exception from §5, which the global handler turns into the error envelope (§13).

9. Document Lifecycle & Versioning

9.1 Version history state

9.2 Soft-delete & restore

9.3 Asynchronous post-upload processing

Uploads return to the user as soon as the S3 PUT and sp_document_upload_commit succeed — thumbnail generation never blocks the upload response. The frontend shows a "generating preview…" placeholder (§22.4) until the callback lands and the document's processing status flips to COMPLETED.

10. Private Storage & Signed URL Security

10.1 Why this is the README's centerpiece

This is written up verbatim as its own prominent section in README.md (§32), because it is the single design decision that most distinguishes this project from a beginner's "upload to S3" tutorial:

• The bucket is private because any public bucket is one misconfigured object ACL away from an open data leak — there is no reason a company's contracts and HR letters should ever be one guessable URL away from the public internet.
• The backend generates the signed URL, never the frontend, because the frontend cannot be trusted to enforce authorization — only server-side code that has just checked "does this user have VIEWER+ on this document" can be trusted to mint a credential that grants access to it.
• The URL expires in minutes, not hours, so a leaked link (forwarded email, browser history, proxy log) stops working quickly — long-lived sharing instead goes through the explicit, revocable, audit-logged share_links mechanism (§17), never a long-TTL presigned URL.

11. Audit Logging

Every action that touches access or data — login, folder/document create, upload, new version, download-URL issuance, share grant/revoke, share-link create/revoke, soft delete, restore, admin role change — writes one audit_logs row inside the same transaction as the action itself (never as an afterthought that could silently fail). Combined with the append-only document_versions history, an ADMIN can always answer "who has touched this file, and how" from data alone, without trusting anyone's memory of what happened.

12. API Design Conventions

13. Response & Error Envelope

13.1 Success — single resource

{
  "success": true,
  "data": { "id": 482, "name": "MSA-2026-NovaTrail.pdf", "currentVersion": 2 }
}

13.2 Success — paginated list

{
  "success": true,
  "data": [ /* array of resources */ ],
  "meta": { "page": 1, "limit": 20, "total": 86, "totalPages": 5 }
}

13.3 Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request payload failed validation.",
    "details": [ { "field": "name", "message": "name is required" } ]
  }
}

14. Error Code Catalog

15. API — Auth & Users

POST/api/v1/auth/login

Public Authenticates a user and issues tokens.

POST/api/v1/auth/refresh

Public Exchanges a valid refresh token for a new pair (rotation — old token invalidated).

POST/api/v1/auth/logout

Revokes the caller's current refresh token.

GET/api/v1/users/me

Returns the caller's profile and global role.

POST/api/v1/users

ADMIN Invites a new user (no public self-registration — this is an internal corporate tool).

GET/api/v1/users

ADMIN Paginated team member list (§24).

PUT/api/v1/users/:id

ADMIN Updates role or status (ACTIVE/DISABLED). A disabled user's refresh tokens are revoked immediately.

16. API — Folders

POST/api/v1/folders

GET/api/v1/folders/:id/children

Returns the immediate child folders and documents of a folder — backs the browser screen's breadcrumb navigation (§22.3). Omitting :id (i.e. /folders/root/children) returns the caller's accessible top-level folders.

PUT/api/v1/folders/:id

Rename and/or move (change parentFolderId). Requires EDITOR+ on the folder and on the destination parent. Backed by sp_folder_rename_move, which also rejects moving a folder into its own descendant (cycle check).

DELETE/api/v1/folders/:id

Soft-deletes the folder and cascades to every descendant folder/document (sp_folder_soft_delete). Requires OWNER on the folder.

POST/api/v1/folders/:id/restore

Restores from trash — 422 PARENT_FOLDER_NOT_FOUND if the immediate parent is still deleted (restore the parent first).

17. API — Documents, Upload & Versions

POST/api/v1/documents/uploads/initiate

Step 1 of the direct-to-S3 upload flow (§10).

// Step 2 (frontend, not an API endpoint on this backend): PUT the file bytes directly to S3
await fetch(uploadUrl, { method: 'PUT', body: file, headers: { 'Content-Type': file.type } });

POST/api/v1/documents/uploads/complete

Step 3 — confirms the S3 object exists (a HEAD request against S3) and commits the document + first version.

GET/api/v1/documents/:id

Full detail including current version, thumbnail (if ready), and the caller's effective permission.

PUT/api/v1/documents/:id

Metadata-only update (name, description, tags, folder move). Requires EDITOR+.

DELETE/api/v1/documents/:id

Soft delete (sp_document_soft_delete). Requires OWNER.

POST/api/v1/documents/:id/restore

Restores from trash. Requires OWNER.

POST/api/v1/documents/:id/versions/initiate & POST/api/v1/documents/:id/versions/complete

Same three-step pattern as initial upload, scoped to an existing document; requires EDITOR+; backed by sp_document_new_version (§8.2).

GET/api/v1/documents/:id/versions

Lists all versions, newest first, each with its own download link endpoint.

18. API — Download, Preview & Sharing

GET/api/v1/documents/:id/download

GET/api/v1/documents/:id/preview

Same authorization, returns a presigned GET URL with response-content-disposition: inline for browser-renderable types (PDF, PNG, JPG); other types fall back to the thumbnail.

GET/api/v1/documents/:id/thumbnail

Returns a presigned GET URL for the Lambda-generated thumbnail, or 404 with code THUMBNAIL_NOT_READY while processing is still pending.

POST/api/v1/documents/:id/permissions

Grants VIEWER/EDITOR/OWNER to another user. Requires OWNER on the document.

GET/api/v1/documents/:id/permissions

Lists everyone with explicit access (direct grants only — inherited folder access is shown separately in the UI, §22.5).

DELETE/api/v1/documents/:id/permissions/:userId

Revokes a direct grant. Requires OWNER; cannot revoke the last remaining OWNER.

POST/api/v1/documents/:id/share-links

GET/api/v1/documents/:id/share-links

Lists active/expired/revoked links for a document, with download counts.

DELETE/api/v1/share-links/:id

Revokes a link immediately (sets revoked_at) — any outstanding copy of the URL stops working on its next use.

19. API — Public Share Link & Audit Log

GET/s/:token

Public, no auth Backs the public landing page (§22.11).

POST/api/v1/internal/processing-callback

Internal, HMAC-signed Called by the Lambda worker after thumbnail/metadata processing (§9.3). Verified via X-Signature (HMAC-SHA256 of the raw body with a secret shared only with the Lambda's environment) — never a user JWT.

GET/api/v1/audit-logs

ADMIN Paginated, filterable by entityType, entityId, userId, action, and a date range.

20. Full Endpoint Index

21. Frontend Architecture

21.1 Data flow

21.2 Upload is a client-orchestrated three-step flow

22. Screens & UI/UX Specification

Eleven screens, scoped to only the fields the corresponding record actually needs (§2) — no metadata builder, no tagging taxonomy admin, no content-based search UI.

23. UI & Validation Standards

• Required fields marked with a trailing *; the same Zod schema used client-side mirrors the CI4 rule group server-side.
• Permission-aware UI: an action the caller cannot perform is hidden, not merely disabled — a VIEWER's context menu simply has fewer items than an OWNER's, rather than greyed-out ones with a tooltip explaining why.
• Loading state: skeletons matching the real layout (folder grid, table rows) rather than a bare spinner.
• Empty vs. no-results: "This folder is empty" (creation CTA) is always visually distinct from "No documents match your search" (clear-filters action).
• Destructive actions (delete, revoke share, disable user) always confirm by naming the specific record and its consequence.
• Toasts confirm every successful mutation ("Document restored", "Link revoked"); field-level errors surface inline first.

24. Pagination, Filtering & Sorting

GET /api/v1/documents?folderId=42&page=1&limit=20&search=nova&mimeType=application/pdf&sort=updatedAt&direction=desc

Every list endpoint shares one pagination request shape (page ≥ 1 default 1, limit 1-100 default 20, resource-specific filters, sort allow-listed per resource, direction asc|desc) and one paginated response shape (§13.2), so the shared DataTable/grid component works identically across Documents, Folders (children), Users, and Audit Logs.

25. Testing Strategy

26. API Documentation (OpenAPI)

Generated from PHP doc-comment annotations via zircote/swagger-php, served at /api/docs in non-production environments. Every route's rule group is mirrored in its @OA\RequestBody schema so the generated spec cannot silently drift from the actual validation rules enforced in §12–§19.

27. Docker & Local Development

# infrastructure/docker-compose.yml services
api         # PHP-FPM + CodeIgniter 4, port 8080
web         # nginx serving the built React app in dev-parity mode
mysql       # MySQL 8, auto-runs migrations + stored-procedure scripts + DemoSeeder on first boot
localstack  # emulates S3 + Lambda locally — no AWS account needed for local dev
mailhog     # catches the ADMIN user-invite emails

docker compose up brings up the full stack; php spark db:seed DemoSeeder loads the fictional "Meridian Consulting Group" with sample folders (Client Contracts, HR Records, Compliance) and synthetic PDF/DOCX/image documents for screenshots.

28. AWS Deployment Architecture

Deployment infra is documented (Terraform snippets under infrastructure/aws/) but treated as optional for a reviewer — the Docker Compose stack in §27 is the primary "clone and run" path.

29. Build Phases & Roadmap

30. Risks & Mitigations

31. Copyright, Trademark & Branding

Arsi India Info — Innovate · Integrate · Elevate.
Author of record for this repository and every file in it.

31.1 Two-layer licensing

Source code is released under the MIT License (already present at the repo root). The Arsi India Info name and logo are covered separately by TRADEMARK.md: forks and derivatives are welcome, but must not present themselves as Arsi India Info's own product or reuse its logo/branding.

31.2 Where the signature lives

31.3 Honest limits of watermarking a public repo

A footer string or logo can be stripped by a determined fork. Real proof of authorship comes from GitHub itself: commits under the Arsi India Info GitHub org, signed commits, a CODEOWNERS file, and SHA-256 checksums on tagged releases. This plan treats visible branding as presentation, not enforcement.

32. Documentation Set & Portfolio Usage

33. Definition of Done

• All 31 endpoints in §20 implemented, validated, and covered by at least one feature test
• Every screen in §22 has loading, empty, error, and success states implemented — not just the happy path
• A full document lifecycle (upload → new version → internal share → external share link → download via the public page → soft delete → restore) is demonstrable end-to-end with one seed script and no manual DB edits
• The permission-inheritance guardrail test (§6.3) and the version-numbering concurrency test (§25) both pass in CI
• The documents S3 bucket has Block Public Access verified enabled, and a CI check fails the build if the Terraform plan would ever change that
• README, API docs, and the portfolio demo script (§32) are complete enough that someone who has never seen the repo can run it in under 10 minutes
• Branding present per the §31.2 table; LICENSE and TRADEMARK.md committed

© 2026 Arsi India Info. All rights reserved.

Cloud Document Management System — source code licensed under MIT · name & logo protected under TRADEMARK.md
arsiindiainfo.com · github.com/arsiindiainfo