Server File Manager Platform (PHP + Go File Engine)

⚡️ A governance-focused, multi-tenant file management platform written in Go and PHP ⚡️
Designed to operate directly on real storage backends (local/mounted SMB/NFS/SFTP, with adapter-based extensibility for S3/GCS). It centralizes access to shared storage with RBAC + path-based ACL, async mutations, baseline task audit events, and a baseline-validated quarantine → scan → promote guardrail flow (local semantics).

---

Project status

This repository documents an evolving architecture.

Legend:

• ✅ implemented
• 🟡 in progress
• 🔒 planned / target state

Note

Current maturity note: Some controls are documented as the target state. The project roadmap tracks what has already been implemented vs what is intended. Validation source of truth: Please see docs/capability-ledger.md for runnable commands that validate each implementation.

---

Documentation map

Architecture & Implementation:

• API Reference: docs/api-reference.md
• API Versioning Policy: docs/api-versioning-policy.md
• Client SDKs (thin): docs/client-sdks.md
• Architecture Overview: docs/architecture.md
• Architecture Boundaries: docs/architecture_boundaries.md
• Auth Model (RBAC/JWT): docs/auth.md
• Threat Model: docs/threat-model.md
• Observability: docs/observability.md
• Roadmap (staged milestones): docs/roadmap.md
• Setup/onboarding guide: docs/setup.md
• Decisions and rationale: docs/adr

Governance & Status:

• Capability Ledger (Truth): docs/capability-ledger.md
• Route maturity matrix: docs/route-maturity-matrix.md
• Project Alignment: docs/project-alignment-review.md
• Governance (merge gates): docs/governance.md
• Branch protection mapping: docs/branch-protection-mapping.md

---

Why this exists

Many organizations rely on direct file server access (shared drives/SSH/FTP) to create folders, upload documents, and manage structured storage. This is:

• hard to audit,
• easy to misuse (authorization drift, unsafe paths),
• inconsistent with compliance requirements,
• operationally fragile under load.

This platform provides a centralized, permissioned interface that controls and records every filesystem mutation.

---

Key flows

sequenceDiagram
    autonumber
    participant U as User / UI
    participant FE as File Engine (API)
    participant DB as Postgres
    participant Q as Redis Queue
    participant W as Worker
    participant ST as Storage (S3/Local)

    Note over U, ST: Phase 1: Initiate & Upload

    U->>FE: POST /v1/uploads:initiate<br/>(path, size, mime)
    FE->>FE: Validate JWT, RBAC, Policy
    FE->>DB: Create Record (State: PENDING, Path: quarantine/...)
    FE-->>U: Return uploadId + uploadUrl

    U->>ST: PUT binary to uploadUrl<br/>(Writes to quarantine/tenant/id/...)
    
    Note over U, ST: Phase 2: Completion & Scan

    U->>FE: POST /v1/uploads/{id}:complete
    FE->>DB: Update State: QUEUED
    FE->>Q: Enqueue Scan Task
    FE-->>U: HTTP 202 Accepted (taskId)

    Q->>W: Pop Task
    W->>ST: Read File Stream
    W->>W: ClamAV Scan (Stream)

    alt Verdict: CLEAN
        W->>ST: Atomic Move<br/>(quarantine/... -> tenants/...)
        W->>DB: Update State: SUCCESS
        W->>DB: Log Audit (Promote)
    else Verdict: MALICIOUS
        W->>ST: Move to malware/... (Hold)
        W->>DB: Update State: QUARANTINED
        W->>DB: Log Audit (Security Alert)
    end

Loading

---

Quickstart (local development)

Requirements:

• Go 1.26+
• Docker Engine / Docker Desktop + Compose v2 (optional; only needed for containerized dependencies)
• curl (optional; only needed for manual API calls)

1) Run the validated baseline checks (recommended)

This is the only baseline-validated quickstart today.

./file-engine/scripts/dev.sh

2) One-command onboarding + demo evidence

make bootstrap && make demo

This command pair regenerates docs, enforces architecture boundaries, runs doc drift checks, executes the deterministic 5-minute demo script, and prints evidence links for generated docs.

3) Optional: run the async folder flow integration test alone

cd file-engine && go test ./tests/integration -run TestAsyncCreateFolderFlow -v

4) Optional: local File Engine run (scaffold-level, for debugging)

This brings up Redis/Postgres in Docker and runs the API/worker locally for debugging. REST endpoints include baseline create-folder/task-status and upload lifecycle paths; treat this path as local debugging rather than the canonical baseline verification flow.

cd file-engine
docker compose up -d redis postgres

export REDIS_ADDR="localhost:6379"
export POSTGRES_DSN="postgres://fileengine:fileengine@localhost:5432/fileengine?sslmode=disable"
export STORAGE_BACKEND="local"
export FILE_BASE_ROOT="$PWD/data"
export JWT_SECRET="dev-secret"
export TENANT_MEMBERSHIPS="dev-admin=dev-tenant"

# Optional worker guardrails (defaults shown in parentheses):
# export WORKER_STATUS_RETRY_ATTEMPTS="3"
# export WORKER_STATUS_RETRY_DELAY_MS="25"
# export WORKER_TASK_PROCESS_TIMEOUT_MS="30000"

go run ./cmd/migrate

API terminal:

cd file-engine && go run ./cmd/file-engine

Worker terminal:

cd file-engine && go run ./cmd/worker

Dev JWT (HS256 with JWT_SECRET=dev-secret, sub=dev-admin, roles=["admin"]):

export JWT="***"

5) Canonical compose entry point

Use repository-root docker-compose.yml as the primary developer compose entry point.

file-engine/docker-compose.yml remains only as a compatibility mirror and should not be treated as the canonical source.

Default ports:

• HTTP: 8080
• gRPC: 50051
• Redis: 6379
• Postgres: 5432

Note

All setup flows (local File Engine run, canonical root compose, dev JWT) are documented in docs/setup.md.

---

Deployment (dev/stage/prod + kind + rollback)

• Environment profile templates are versioned in env/.env.dev.example, env/.env.stage.example, and env/.env.prod.example.
• Config/secret separation and required runtime wiring checks are documented in docs/deployment-profiles.md and validated with ./scripts/check-runtime-wiring.sh --profile prod.
• Kubernetes smoke and rollback drill paths are script-backed via ./scripts/k8s/kind_smoke.sh and ./scripts/drills/k8s_rollback_drill.sh.
• Release versioning + changelog + rollback discipline is documented in docs/release/versioning-and-rollback.md.

---

Repository structure

file-server-management/
├─ frontend/                  # Static thin-client demo console (no Node build)
├─ backend/                   # Laravel control plane
├─ file-engine/               # Go File Engine (API + Worker)
└─ docs/
   ├─ adr/                    # Architectural Decision Records
   ├─ architecture.md         # Platform architecture
   ├─ api-reference.md        # API surface (gRPC + HTTP)
   ├─ auth.md                 # AuthN/AuthZ model
   ├─ observability.md        # Logs/metrics/tracing expectations
   ├─ threat-model.md         # Security model + STRIDE notes
   └─ setup.md                # Local development setup

---

Disclaimer

This project is a work in progress. Some controls are documented as “target state” and may not be fully implemented yet.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

🔼 Back to top