Army Memo Maker

A modern web application for creating professional Army memorandums in perfect accordance with AR 25-50. Fast, secure, and DoD network compatible.

🌐 Live Application: armymemomaker.com

✨ Features

🎯 Core Functionality

• Professional memo generation - Typst-powered formatting through the shared armymemo library
• Dual input modes - Choose between markdown-like syntax or guided form builder
• Real-time compilation - PDFs generated on-demand with a fast Typst pipeline
• Document management - Save, edit, and organize your memos with user accounts

🎨 Modern Interface

• Dark/Light mode - Toggle between themes with persistent preferences
• Responsive design - Works seamlessly on desktop and mobile devices
• Clean typography - Professional appearance with modern fonts and spacing
• Accessibility focused - Built with inclusive design principles

🔒 Security & Reliability

• SSL/TLS encryption - End-to-end security with Let's Encrypt certificates
• User authentication - Secure account system with password hashing
• Input validation - Comprehensive sanitization and validation
• CAPTCHA protection - Spam prevention (configurable for testing environments)

⚡ Performance & Modern Tooling

• Direct PDF rendering - Standard memo generation returns PDFs immediately from the app
• Fast dependency management - uv package manager with lockfile support
• Shared rendering engine - Web app imports the standalone armymemo package directly
• Reproducible benchmark path - make benchmark exercises representative Typst renders
• Modern Python packaging - pyproject.toml with standardized build system
• Async validation pipeline - Huey remains in place for validation and longer-running background jobs
• Docker containerization - Consistent deployment across environments
• Auto-deploy - Watchtower monitors Docker Hub for automatic updates

🚀 Quick Start

Prerequisites

• Docker and Docker Compose - For containerized development
• Git - Version control
• uv (optional) - For local Python development: curl -LsSf https://astral.sh/uv/install.sh | sh

Development Setup

Option 1: Docker Development (Recommended)

1. Clone the repository

   git clone https://github.com/jschless/armymarkdown.git
   cd armymarkdown
   

2. Set up environment variables

   # Create environment file with required settings
   export FLASK_SECRET="your-development-secret-key"
   export DISABLE_CAPTCHA="true"  # For development
   export DEVELOPMENT="true"
   

3. Start development environment

   make docker-dev-build
   # or manually:
   # docker compose -f infrastructure/compose/docker-compose-dev.yaml up --build
   

4. Access the application

   • Web interface: http://localhost:8000
   • The application will hot-reload when you make changes

Option 2: Local Python Development

1. Install dependencies with uv

   # Install uv if not already installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Create virtual environment and install dependencies
   uv sync --extra dev
   

2. Set up environment variables

   export FLASK_SECRET="dev-secret-key"
   export DISABLE_CAPTCHA="true"
   export DEVELOPMENT="true"
   

3. Run the application

   # Start the Flask app
   make run
   
   # (Optional) Start Huey task consumer in another terminal
   make huey
   

Production Deployment

1. Configure environment variables on your server

   export FLASK_SECRET="your-secret-key"
   export RECAPTCHA_PUBLIC_KEY="your-public-key"
   export RECAPTCHA_PRIVATE_KEY="your-private-key"
   

2. Deploy with Docker Compose

   make docker-prod
   # or manually:
   # docker compose -f infrastructure/compose/docker-compose.yaml up --build -d
   

3. Optional: Disable CAPTCHA for testing

   export DISABLE_CAPTCHA=true
   

📝 Army Markdown Syntax

Create professional memos using our intuitive markdown-like syntax:

ORGANIZATION_NAME=4th Engineer Battalion
ORGANIZATION_STREET_ADDRESS=588 Wetzel Road
ORGANIZATION_CITY_STATE_ZIP=Colorado Springs, CO 80904

OFFICE_SYMBOL=ABC-DEF-GH
AUTHOR=Joseph C. Schlessinger
RANK=1LT
BRANCH=EN
TITLE=Platoon Leader

MEMO_TYPE=MEMORANDUM FOR RECORD
SUBJECT=Template for Army Markdown

- This memo demonstrates the Army Markdown syntax.

- This item contains sub items:
    - A subitem is created by indenting 4 spaces
    - A second subitem within the same point
        - Here is a sub-sub item

- **Bold text**, *italic text*, and `highlighted text` are supported.

- Point of contact is the undersigned at (719) 555-0123.

Supported Features

• Text formatting: Bold, italic, and highlighted text
• Nested lists: Multi-level indentation with automatic formatting
• Tables: Basic table support for structured data
• Classifications: Support for classified document markings
• Enclosures: Automatic enclosure numbering and references

🏗️ Architecture

Technology Stack

• Backend: Python Flask with Gunicorn WSGI server
• Package Management: uv for fast, reliable dependency resolution
• Build System: Modern Python packaging with pyproject.toml
• Task Queue: Huey with SQLite for asynchronous PDF generation
• Database: SQLite for user accounts and document storage
• PDF Generation: Typst via the standalone armymemo package
• Frontend: Modern CSS with vanilla JavaScript
• Containerization: Docker with multi-stage builds
• Reverse Proxy: Caddy with automatic SSL

System Components

┌─────────────────┐    ┌─────────────────────────────────────┐
│   Caddy Proxy   │────│   Flask App + Huey Task Consumer   │
│   (Port 80/443) │    │   (Port 8000)                      │
│   (Auto SSL)    │    │                                     │
└─────────────────┘    └─────────────────────────────────────┘
                                        │
                       ┌────────────────┴────────────────┐
                       │          SQLite Database        │
                       │   (Users, Documents, Tasks)     │
                       └─────────────────────────────────┘

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
FLASK_SECRET	Flask session secret key	✅	-
RECAPTCHA_PUBLIC_KEY	reCAPTCHA site key	✅	-
RECAPTCHA_PRIVATE_KEY	reCAPTCHA secret key	✅	-
DISABLE_CAPTCHA	Disable CAPTCHA for testing	❌	false
DEVELOPMENT	Enable development mode	❌	false

Security Configuration

The application includes several security measures:

• Content Security Policy (CSP) with restricted script sources
• SSL/TLS encryption with automatic certificate renewal
• Input sanitization and validation on all user inputs
• Rate limiting and CAPTCHA protection against abuse
• Secure session management with httpOnly cookies

🧪 Testing

Running Tests with Make Commands

# Run all tests with coverage
make test-cov

# Run all tests (excluding selenium)
make test

# Run fast tests only
make test-fast

# Run verbose tests
make test-verbose

# Run specific test file
PYTHONPATH=. uv run pytest tests/test_input_validation.py -v

# Run tests matching a pattern
PYTHONPATH=. uv run pytest tests/ -k "test_memo" -v

Docker Testing Environment

# Run tests in Docker container
docker compose -f infrastructure/compose/docker-compose-dev.yaml exec flask_app make test

# Or build and run tests in isolated container
docker build -f infrastructure/docker/Dockerfile.development -t armymarkdown-test .
docker run --rm armymarkdown-test make test

Test Environment Variables

The tests require these environment variables:

export FLASK_SECRET="test-secret-key-for-ci"
export RECAPTCHA_PUBLIC_KEY="test-public-key"
export RECAPTCHA_PRIVATE_KEY="test-private-key"
export DISABLE_CAPTCHA="true"
export DEVELOPMENT="true"

📚 API Documentation

Endpoints

• GET / - Main memo editor interface
• GET /form - Form-based memo builder
• GET /history - User's saved documents (requires authentication)
• POST /process - Generate and return a memo PDF directly
• POST /save_progress - Save draft (requires authentication)

Authentication

• GET /login - User login page
• POST /login - Process login credentials
• GET /register - User registration page
• POST /register - Create new user account
• GET /logout - End user session

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork and clone the repository

   git clone https://github.com/YOUR-USERNAME/armymarkdown.git
   cd armymarkdown
   

2. Set up development environment

   # Install uv if needed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies
   uv sync --extra dev
   

3. Create a feature branch

   git checkout -b feature/amazing-feature
   

4. Make your changes with tests

   # Run tests frequently during development
   make test
   
   # Check code quality
   make lint
   make format
   

5. Commit and push

   git add .
   git commit -m "Add amazing feature"
   git push origin feature/amazing-feature
   

6. Open a Pull Request with a clear description of your changes

Code Standards

• Python: Follow PEP 8, use type hints where helpful
• Code Quality: Use ruff for linting and formatting
• Testing: Write tests for new functionality (pytest)
• Dependencies: Use uv add for new dependencies
• Documentation: Update README and docstrings as needed
• Docker: Ensure both development and production builds succeed

Quality Checks

Before submitting a PR, ensure these pass:

# Code formatting and linting
make format
make lint

# Security scanning
make security

# Full test suite with coverage
make test-cov

# Run all quality checks
make check

Development Tools & Configuration

The project uses modern Python tooling for development:

• pyproject.toml - Centralized project configuration
• uv.lock - Locked dependency versions for reproducible builds
• ruff - Fast Python linter and formatter (replaces flake8, black, isort)
• bandit - Security vulnerability scanning
• safety - Dependency vulnerability checking
• pytest - Testing framework with coverage reporting

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• armymemo - Standalone Army memo rendering library
• Flask - Web framework
• Huey - Lightweight task queue

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Contact the maintainer

---