How humdinger-g/short-links works
1. System shape
- This repository implements a short-link platform with two separate clients:
- a FastAPI backend API in app/
- a lightweight Streamlit UI in streamlit_app/
- The backend owns all business logic, persistence, authentication, caching, and background cleanup.
2. Request entrypoints
- The backend starts from app/main.py, with app lifecycle wiring in app/lifecycle.py.
- API routes are grouped under app/api/router.py and split into:
- app/api/routes/auth.py
- app/api/routes/links.py
- The Streamlit app is a thin consumer that calls the API through streamlit_app/api_client.py; it does not talk directly to the database.
3. Domain subsystems
- Auth subsystem: app/auth/ handles registration, login, token/security concerns, and auth dependencies.
- Links subsystem: app/links/ contains the link business service, link-specific schemas, Redis cache helpers, and cleanup logic.
- Persistence subsystem: app/db/ contains SQLAlchemy models, session setup, and base metadata.
- Configuration subsystem: app/settings.py centralizes environment-driven settings.
4. Core data flow for authentication
- User registration and login are handled via the auth routes.
- Credentials are validated, passwords are hashed, and bearer tokens are issued.
- Protected link operations use auth dependencies to resolve the current user and enforce ownership checks.
- User records are stored in PostgreSQL in the users table.
5. Core data flow for short links
- POST /links/shorten creates link records in PostgreSQL.
- A link may be anonymous or owned by an authenticated user.
- The service supports custom_alias and expires_at.
- GET /links/{short_code} resolves the short code, increments usage counters, updates last-used timestamps, and returns a redirect response.
6. Link lifecycle and ownership
- PUT /links/{short_code} and DELETE /links/{short_code} are restricted to the owner.
- The service layer is the boundary where ownership, alias uniqueness, expiration, and activity rules are enforced.
- Expired links are treated as inactive even before physical cleanup occurs.
7. Caching and invalidation
- Redis is used as a read-through cache for:
- GET /links/search
- GET /links/{short_code}/stats
- Cache invalidation happens on link creation, redirect, update, delete, and background cleanup.
- Cache TTL is constrained both by global settings and by the link’s own expires_at, so expired data cannot outlive the link.
8. Background cleanup and archival
- app/lifecycle.py and app/links/cleanup.py support periodic background jobs.
- Two cleanup policies exist:
- automatic removal of links after expires_at
- automatic removal of unused links after UNUSED_LINK_DAYS
- Deleted links are archived into archived_links, preserving history and deletion reason (expired or unused).
- GET /links/history/expired exposes that archived history.
9. Database and migrations
- PostgreSQL is the primary durable store.
- SQLAlchemy 2 is used for the ORM/persistence layer.
- Alembic manages schema evolution, with migrations in alembic/versions/.
- The README indicates Docker Compose runs alembic upgrade head before starting the app, so schema migration is part of startup orchestration.
10. Deployment and runtime environment
- docker-compose.yml coordinates the backend, PostgreSQL, Redis, and Streamlit.
- Dockerfile packages the backend runtime.
- .env.example documents the operational configuration:
- database and Redis URLs
- auth secret and token TTL
- cache TTL
- cleanup intervals
- public base URL used by the UI when displaying short links
11. Testing and validation boundaries
- The repo is organized for both unit and functional validation:
- tests/unit/ covers auth, DB session/lifecycle, link service/cache/cleanup, and schemas
- tests/functional/ exercises the API end-to-end
- tests/load/ contains a Locust scenario for traffic testing
- Coverage artifacts in htmlcov/ and reports/ indicate the project is already instrumented for quality tracking.
12. Architecture summary
- Conceptually, the backend is a three-layer system:
- API layer: FastAPI routes and request/response schemas
- Domain layer: auth and link services, business rules, cleanup logic
- Infrastructure layer: PostgreSQL, Redis, SQLAlchemy, Alembic, and background tasks
- The Streamlit app is an external presentation client on top of that API, not part of the core service boundary.
Main entry points: service.py Link service · router.py API router · links.py Link routes · main.py App start
Components 21
Client
Thin Streamlit presentation layer
- Streamlit UI · Lightweight user-facing client
streamlit_app/app.py - API client · Streamlit-side API consumer
streamlit_app/api_client.py
API
FastAPI entrypoints and request routing
- App start · Backend application entrypoint
app/main.py - API router · Top-level API router composition
app/api/router.py - Auth routes · Registration and login endpoints
app/api/routes/auth.py - Link routes · Short-link CRUD, redirect, search, and history endpoints
app/api/routes/links.py
Domain
Auth and link business logic
- Auth deps · Current-user resolution and ownership enforcement
app/auth/dependencies.py - Security · Password hashing and bearer token handling
app/auth/security.py - Auth schemas · Authentication request and response models
app/auth/schemas.py - Link service · Link creation, lookup, update, ownership, and expiry rules
app/links/service.py - Cleanup · Expiration and unused-link archival jobs
app/links/cleanup.py - Link schemas · Link request, response, and history models
app/links/schemas.py
Infrastructure
Persistence, cache, settings, and runtime wiring
- Lifecycle · App startup and background task wiring
app/lifecycle.py - Link cache · Read-through caching and invalidation for search and stats
app/links/cache.py - DB session · Database engine and session management
app/db/session.py - Data models · SQLAlchemy models and metadata for users and links
app/db/models.py - Base metadata · Declarative base and shared metadata
app/db/base.py - Settings · Environment-driven application configuration
app/settings.py
Delivery
Migrations and validation
- Alembic env · Migration environment and schema orchestration
alembic/env.py - Schema mig · Versioned schema evolution scripts
alembic/versions - API tests · End-to-end API validation coverage
tests/functional/test_links_api.py
Connections 26
- App start → API router: mounts · Registers API routes
- App start → Lifecycle: starts · Initializes startup/shutdown hooks
- App start → Settings: reads · Loads runtime configuration
- API router → Auth routes: includes · Adds auth endpoints
- API router → Link routes: includes · Adds link endpoints
- Auth routes → Security: uses · Hashes passwords and issues tokens
- Auth routes → Auth schemas: validates · Shapes auth requests and responses
- Link routes → Link service: calls · Delegates link operations to the service layer
- Link routes → Auth deps: protects · Resolves authenticated users for protected actions
- Link routes → Link schemas: validates · Shapes link and history payloads
- Auth deps → Security: verifies · Checks bearer tokens and identity
- Link service → DB session: persists · Reads and writes link and user records
- Link service → Data models: maps · Operates on ORM entities
- Link service → Link cache: invalidates · Maintains cache coherence
- Link service → Settings: uses · Applies cache and cleanup configuration
- Link service → Auth deps: enforces · Checks ownership for updates and deletes
- Link cache → DB session: reads through · Cache misses fall back to persistence
- Cleanup → DB session: archives · Moves expired and unused links to history
- Cleanup → Link cache: purges · Invalidates stale cached entries
- Lifecycle → Cleanup: schedules · Runs periodic maintenance jobs
- Data models → Base metadata: extends · Builds the declarative model layer
- Alembic env → Base metadata: imports · Binds migration metadata
- Alembic env → Schema mig: runs · Applies versioned schema changes
- Streamlit UI → API client: uses · Delegates all backend calls to the client
- API client → API router: calls · Consumes the backend API
- API tests → API router: exercises · Validates end-to-end API behavior