another-s3-manager: Instructions file for Codex

Project instructions

This file is the canonical project guide shared by Claude Code and Codex. When this repository is checked out inside the workspace, a session started directly here must, before planning or editing, read the workspace root guide and every applicable document in the neutral contract directory completely. Those shared project obligations remain applicable, but the full workspace harness (MCP, hooks, roles, and skills) is guaranteed only for sessions started from the workspace root. In a standalone clone where that parent workspace is absent, this guide remains self-contained and workspace extras are unavailable. Start from the workspace root when shared tooling is required.

Another S3 Manager

Lightweight web UI for managing files in S3 and S3-compatible storage.

This is a public repository. Never commit, push, or include in PR descriptions / commit messages / issue bodies any absolute paths from a developer's local filesystem (e.g. D:\..., /Users/..., C:\..., /home/...). Specs and plans for this project live out-of-repo per the shared workspace specs-and-plans contract — when referencing them in a PR description, use only the relative tail (e.g. specs/2026-05-02-foo-design.md (out-of-repo)), never the full absolute path. Personal directory structure leaking into a public repo is a privacy issue and looks unprofessional.

Stack

• Backend: Python 3.13+, FastAPI, Boto3, JWT auth (cookie-based), per-username ban for brute-force defense
• Frontend: React + Mantine (Vite); FastAPI serves the built SPA at /
• Deployment: Docker, Docker Compose, Kubernetes (chart hosted at github.com/kruchenburger/helm — in progress)
• Package manager: uv

Structure

another-s3-manager/
├── src/
│   └── another_s3_manager/
│       ├── __init__.py
│       ├── main.py          # FastAPI app, API endpoints
│       ├── auth.py           # JWT auth, CSRF, ban logic
│       ├── config.py         # Config management (config.json)
│       ├── constants.py      # App constants, paths
│       ├── database.py       # SQLAlchemy engine + session_scope()
│       ├── models.py         # ORM models (User, Role, Ban)
│       ├── s3_client.py      # S3 client, role management
│       ├── users.py          # User management (SQLite via SQLAlchemy)
│       ├── utils.py          # Validation, sanitization
│       └── static/app/       # React SPA build output (generated, not tracked)
├── migrations/               # Alembic migrations (env.py + versions/)
├── alembic.ini
├── tests/                    # pytest tests
├── frontend/                 # React + Mantine source
├── data/                     # Runtime data (not tracked)
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
└── uv.lock