Overview
========

ushman.dev is a Django application using Wagtail for content management.
The application is deployed to Heroku, with PostgreSQL for persistent
application data and AWS services for file storage, content delivery,
and email.

Technology
----------

:Language:
    Python

:Application framework:
    Django

:Content management:
    Wagtail

:Database:
    PostgreSQL

:Front end:
    Bootstrap

:Application hosting:
    Heroku

:Media and static files:
    Amazon S3 and CloudFront

:Email:
    Amazon SES

Specific Python and package versions are maintained in the application's
runtime and dependency configuration rather than duplicated in this
documentation.

Configuration
-------------

Environment-specific configuration is supplied through Heroku Config
Vars and is kept outside the application source code.

This includes service credentials, database configuration, email
configuration, storage settings, and other values that differ between
deployment environments.

Credentials and other sensitive configuration values are not included
in this documentation.

Infrastructure
--------------

The application runs on Heroku using a managed PostgreSQL database.
Heroku manages TLS certificates for the application's public domains.

DNS is managed separately from the application platform.

Static files and uploaded media are stored in Amazon S3 and delivered
through CloudFront. S3 content is not exposed directly to the public;
CloudFront provides the public delivery layer.

Development Workflow
--------------------

Source code is maintained in Git and hosted on GitHub. Development is
performed locally using feature branches, with changes reviewed through
pull requests before they are merged.

Automated tests are run as part of the development workflow. Pull
requests can also be deployed to temporary Heroku Review Apps when an
isolated environment is useful for testing or review.

The application has persistent staging and production environments.
Changes are deployed to staging for integration testing before being
manually promoted to production.

.. warning::

   Application code should never be modified directly in a deployed
   environment. Deployed instances are disposable and changes made
   outside the source-control and deployment workflow will be lost.

Database
--------

The application uses PostgreSQL in deployed environments. Local
development also uses PostgreSQL so that development behavior closely
matches staging and production.

Development and test environments use their own data. Automated tests
create predictable test data as needed and do not depend on copies of
the production database.

Database schema changes are managed through Django migrations and are
committed to source control with the application code.

Documentation
-------------

This documentation is built with Sphinx using reStructuredText and the
Read the Docs Sphinx theme. Documentation source files are maintained
in the ``docs/`` directory of the application repository.

The documentation is maintained alongside the application so that
changes to architecture, configuration, deployment procedures, and
other technical decisions can be documented as the application evolves.

To build the documentation locally:

.. code-block:: console

   cd docs
   make html

The generated HTML is deployed with the application and is publicly
available at ``/docs/``.