add project structure files

PROJECT.md

@@ -0,0 +1,104 @@
+# FlaskPaste
+
+## Purpose
+
+FlaskPaste is a lightweight, security-hardened pastebin REST API for self-hosted deployments. It provides a minimal, dependency-light alternative to public pastebin services, designed for environments where data privacy, authentication control, and operational simplicity are priorities.
+
+## Problem Statement
+
+Public pastebin services present risks:
+- Data sovereignty concerns (content stored on third-party infrastructure)
+- Limited authentication options
+- No control over retention policies
+- Abuse/spam from other users affecting service reliability
+- Feature bloat and complex UIs when only an API is needed
+
+## Solution
+
+A self-hosted pastebin API that:
+- Stores pastes locally in SQLite
+- Supports client certificate authentication via reverse proxy
+- Automatically expires content based on access patterns
+- Prevents abuse through content-hash deduplication
+- Serves text and binary content with proper MIME detection
+- Runs behind any reverse proxy (nginx, HAProxy, Caddy)
+
+## Success Criteria
+
+```
+┌────────────────────────────────┬────────────────────────────────────────────┐
+│ Criterion                      │ Metric
+├────────────────────────────────┼────────────────────────────────────────────┤
+│ Security                       │ Zero injection vulnerabilities
+│                                │ All OWASP headers implemented
+│                                │ Input validation on all endpoints
+├────────────────────────────────┼────────────────────────────────────────────┤
+│ Reliability                    │ SQLite ACID guarantees
+│                                │ Graceful degradation on errors
+│                                │ Health check endpoint for monitoring
+├────────────────────────────────┼────────────────────────────────────────────┤
+│ Simplicity                     │ Single dependency (Flask)
+│                                │ SQLite for storage (no external DB)
+│                                │ Environment-based configuration
+├────────────────────────────────┼────────────────────────────────────────────┤
+│ Operability                    │ Container-ready (Podman/Docker)
+│                                │ Gunicorn-compatible WSGI
+│                                │ Request tracing via X-Request-ID
+└────────────────────────────────┴────────────────────────────────────────────┘
+```
+
+## Scope
+
+### In Scope
+
+- REST API for paste CRUD operations
+- Text and binary content support
+- Magic-byte MIME type detection
+- Client certificate authentication (via proxy header)
+- Configurable size limits (anon vs authenticated)
+- Time-based expiry with access-touch semantics
+- Content-hash deduplication for abuse prevention
+- Security headers (HSTS, CSP, X-Frame-Options, etc.)
+- Request tracing and structured logging
+- Container deployment support
+- SQLite storage
+
+### Out of Scope
+
+- Web UI / HTML frontend
+- User registration / account management
+- Syntax highlighting
+- Paste forking / versioning
+- Public paste listing / discovery
+- Rate limiting per IP (delegated to reverse proxy)
+- Multi-node clustering / distributed storage
+- Alternative storage backends (S3, PostgreSQL)
+
+## Constraints
+
+- **Single process** - SQLite limits concurrency; scale via multiple containers
+- **Reverse proxy required** - Client cert auth requires TLS termination
+- **No web UI** - API-only; CLI tools (curl, httpie) are the interface
+- **Ephemeral by design** - Pastes expire; not for permanent storage
+
+## Assumptions
+
+- Deployment behind a TLS-terminating reverse proxy
+- Client certificates managed externally (PKI, mTLS)
+- Operators have container runtime (Podman/Docker) or Python venv
+- SQLite performance sufficient for expected load
+
+## Technical Stack
+
+```
+┌─────────────────┬──────────────────────────────────────────────────────────┐
+│ Component       │ Technology
+├─────────────────┼──────────────────────────────────────────────────────────┤
+│ Framework       │ Flask 3.x
+│ Database        │ SQLite 3 (built-in)
+│ WSGI Server     │ Gunicorn (production)
+│ Container       │ Podman / Docker
+│ Testing         │ pytest, pytest-cov
+│ Python          │ 3.11+
+└─────────────────┴──────────────────────────────────────────────────────────┘
+```