docs.appliedpoetics.org API

A lightweight, two-part FastAPI service that manages both user-generated documents and user authentication/profile data. Built for edge compute deployment against MongoDB Atlas.

---

Overview

This repository powers the backend for Applied Poetics. It provides:

• User management — signup, login with JWT bearer tokens, and profile retrieval.
• Document management — create, read, update, and delete user-owned documents.
• Secure defaults — bcrypt password hashing, signed JWTs with best-practice claims, rate limiting, constant-time login, non-root Docker containers, and environment-based configuration.

The API stores user credentials and documents in separate MongoDB collections with indexed lookups for clean data separation and scalability.

---

Features

• User registration and authentication with JWT (PyJWT with iat, jti, iss, aud claims)
• Bearer-token-protected document CRUD endpoints with strict owner authorization
• Rate limiting on authentication and document mutation endpoints
• Constant-time login to prevent username enumeration via timing attacks
• Strong password policy (uppercase, lowercase, digit, special character required)
• MongoDB Atlas integration with TLS and indexed collections
• Global exception handling that prevents internal error leakage
• Environment-driven configuration via .env
• Dockerized multi-stage build optimized for edge compute
• Health check endpoint for container orchestration

---

Tech Stack

• FastAPI — Python web framework
• MongoDB Atlas — hosted document database
• Pydantic — data validation and settings management
• PyJWT — JWT encoding/decoding
• slowapi — rate limiting
• Passlib + bcrypt — password hashing
• Docker — containerized deployment

---

Prerequisites

• Python >= 3.14
• uv (optional but recommended for local development)
• MongoDB Atlas cluster (or a local MongoDB instance)
• Docker (for containerized deployment)

---

Setup

1. Clone the repository

git clone <repository-url>
cd docs.appliedpoetics.org

2. Install dependencies

uv sync

Or with pip:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt  # or install from pyproject.toml

3. Configure environment variables

Copy .env and fill in your values:

cp .env .env.local

Edit .env.local:

MONGO_DB_USER="your-atlas-username"
MONGO_DB_PASSWORD="your-atlas-password"
DATABASE_NAME="docs_appliedpoetics"
SECRET_KEY="your-generated-secret-key"
ACCESS_TOKEN_EXPIRE_MINUTES=30
ALGORITHM="HS256"
ENABLE_DOCS=true

Generating a SECRET_KEY
Run: openssl rand -hex 32
Or: python -c "import secrets; print(secrets.token_hex(32))"

4. Run the server

uvicorn main:app --reload

The API will be available at http://localhost:8000. Interactive documentation is available at /docs.

---

API Endpoints

Users

Method	Endpoint	Auth	Description
POST	/users/signup	No	Register a new user
POST	/users/login	No	Login and receive a JWT
GET	/users/me	Bearer	Get current user profile

Documents

Method	Endpoint	Auth	Description
POST	/documents	Bearer	Create a new document
GET	/documents	Bearer	List your documents
GET	/documents/{id}	Bearer	Get a specific document
PUT	/documents/{id}	Bearer	Update a document
DELETE	/documents/{id}	Bearer	Delete a document

Health

Method	Endpoint	Auth	Description
GET	/health	No	Service health check

---

Docker

Pull the pre-built image (recommended)

The image is automatically built and published to GitHub Container Registry (GHCR) on every push to main or master and every version tag.

docker pull ghcr.io/OWNER/docs-appliedpoetics-org:main

Run from GHCR

docker run -d \
  -p 8000:8000 \
  --env-file .env \
  ghcr.io/OWNER/docs-appliedpoetics-org:main

Build locally

docker build -t docs-appliedpoetics-api .

The image uses a multi-stage build, runs as a non-root user, and includes a built-in health check for edge compute environments.

---

Project Structure

.
├── .env                  # Environment configuration (not committed)
├── .gitignore
├── .github/
│   └── workflows/
│       └── docker-publish.yml  # GitHub Actions: build & push to GHCR
├── Dockerfile            # Multi-stage build for edge compute
├── LICENSE               # MIT License
├── README.md
├── auth.py               # Password hashing, PyJWT encode/decode, get_current_user
├── config.py             # Pydantic settings (reads from .env)
├── database.py           # MongoDB client (TLS, URL-encoded creds), collections, indexes
├── main.py               # FastAPI app entrypoint, middleware, exception handlers, router wiring
├── models.py             # Pydantic models with password-strength validators
├── pyproject.toml        # Project metadata and dependencies
├── routers/
│   ├── users.py          # /users endpoints
│   └── documents.py      # /documents endpoints
└── uv.lock               # Locked dependency tree

---

CI/CD

This repository uses GitHub Actions to automatically build and publish the Docker image to GitHub Container Registry (GHCR).

Workflow

Trigger	Action
Push to main / master	Build and push latest / main tag
Push tag v*.*.*	Build and push semver tags (v1.2.3, v1.2, v1)
Pull request	Build only (no push)

Tags available

• ghcr.io/OWNER/docs-appliedpoetics-org:main
• ghcr.io/OWNER/docs-appliedpoetics-org:v1.2.3
• ghcr.io/OWNER/docs-appliedpoetics-org:v1.2
• ghcr.io/OWNER/docs-appliedpoetics-org:v1
• ghcr.io/OWNER/docs-appliedpoetics-org:sha-abc1234

Setup required

1. Go to Settings → Actions → General in your repository
2. Under Workflow permissions, select Read and write permissions
3. Check Allow GitHub Actions to create and approve pull requests (optional)

The workflow uses the built-in GITHUB_TOKEN — no additional secrets needed.

---

License

This project is licensed under the MIT License.

---

Contributing

Contributions are welcome. Please open an issue or pull request for any improvements.