first commit

ARCHITECTURE.md

@@ -0,0 +1,57 @@
+# NEXPA SourceHub 3.8 Architecture
+
+## Request path
+Internet / Office Network
+→ HTTPS Reverse Proxy
+→ SourceHub Login Gate
+→ NEXPA Core OIDC
+→ Role Binding
+→ FastAPI
+
+## Data
+FastAPI
+→ SQLAlchemy → PostgreSQL
+→ Upload Pipeline → SHA-256 → ClamAV → MinIO
+→ Gitea API
+→ Audit Log
+
+## Download
+Authenticated user
+→ `/api/revisions/{id}/download-link`
+→ 5-minute signed URL
+→ `/download/{id}?token=...`
+→ MinIO/Local object
+
+## Revision contract
+R1 immutable
+R2 append
+R3 append
+...
+Revision addition resets approval flow but never overwrites prior files.
+
+## Approval flow
+UPLOADED
+→ RECEIVED
+→ QA_REVIEW
+→ CONTENT_REVIEW
+→ DEPLOY_REVIEW
+→ APPROVED
+
+## Deployment executor
+APPROVED/Gate-complete item
+→ deploy role only
+→ server-side allowlisted webhook target
+→ HMAC signature
+→ deployment run + audit log
+
+No arbitrary user-supplied shell command is executed.
+
+## Security boundaries
+- Secrets: environment only
+- UI inaccessible before OIDC session
+- Static bypass removed
+- CSRF on mutating requests in OIDC mode
+- Trusted Host list
+- Signed expiring downloads
+- Malware scan before object storage
+- Deployment Gate enforcement