SCD Effort Reporting

A Django web application for Fermilab Scientific Computing Division employees to log and review weekly effort reports. Staff submit entries describing work performed against projects and categories; administrators and auditors can filter, preview, and export the full dataset; key application events are recorded in an audit log.

---

Table of Contents

• Features
• Architecture
• Tech Stack
• Quickstart
• Local Development
• Running Tests
• Docker Deployment
• User Roles
• URL Reference
• Environment Variables
• Management Commands

---

Features

• Effort entries — submit and manage weekly/biweekly/monthly work entries with Markdown descriptions, tags, period dates, group assignment, and flags for privacy, criticality, and highlight rating (0–5 stars)
• HTMX interactions — period chip selector pre-fills date fields; tag autocomplete with chip UI; live Markdown preview; all without full page reloads
• Role-based access — three roles (User, Administrator, Auditor) with enforced permission checks throughout
• Reports — admins and auditors filter entries by author, project, category, and date range; preview results with per-row checkboxes to select a subset; download as plain text, CSV, JSON, XLSX, or PDF
• AI Summary — generate a structured narrative summary of any filtered or selected entries via the Anthropic API; download as plain text or PDF; system prompt and user template are editable from the web UI by admins
• Audit log — WorkItem create/update/delete events, login/logout events, and report exports (including AI summaries) are recorded with actor, IP address, user-agent, and field-level diffs for tracked WorkItem fields
• Taxonomy management — projects, categories, and organisational groups are managed through a tabbed web UI (Admin role required); groups can be assigned to entries to associate work with a team or division
• User management — administrators can create accounts, assign roles, reset passwords, and delete users directly from the web interface
• SSO-ready — local email/password auth via django-allauth; a seam exists for CILogon integration when required

---

Architecture

apps/
├── core/        Dashboard, base templates, shared components
├── accounts/    Custom User model (role + employee_id), profile, admin user management
├── taxonomy/    Project, Category, and WorkGroup models; Tag autocomplete
├── entries/     WorkItem CRUD (the effort entries themselves)
├── reports/     Filter form, five exporters, row selection, AI summary, HTMX preview
└── audit/       AuditLogEntry model, log_event service, signals, middleware, viewer

Each app is independently namespaced and has its own URLs, templates, and tests.

---

Tech Stack

Layer	Choice
Framework	Django 5
Auth	django-allauth ≥ 65 (local; CILogon seam ready)
Frontend	Tailwind CSS 3 via django-tailwind, HTMX 2
Database	PostgreSQL 16 (production), SQLite (local dev fallback)
PDF export	reportlab (pure Python, no system dependencies)
XLSX export	openpyxl
AI summary	Anthropic Python SDK (claude-sonnet-4-6 by default)
Filtering	django-filter
Container	Docker + Caddy (reverse proxy + automatic TLS)
Tests	pytest-django

---

Quickstart

The fastest way to get running — one command handles everything:

# macOS / Linux
git clone https://github.com/your-org/SCD-Reporting.git
cd SCD-Reporting
./bootstrap.sh --admin-password yourpassword

# Windows (PowerShell)
git clone https://github.com/your-org/SCD-Reporting.git
cd SCD-Reporting
.\bootstrap.ps1 -AdminPassword yourpassword

The script creates a virtual environment, installs dependencies, migrates the database, seeds initial data, and starts the server at http://localhost:8000. Log in with scd-admin@fnal.gov and the password you provided.

To enable the AI Summary feature, pass your Anthropic API key:

./bootstrap.sh --admin-password yourpassword --anthropic-key sk-ant-...

For platform-specific prerequisites and manual setup steps see docs/quickstart.md.

---

Local Development

Prerequisites

• Python 3.12+
• Node.js 20+ (optional — Tailwind falls back to the Play CDN in dev mode)
• Git

Setup

The bootstrap.sh / bootstrap.ps1 script handles all of the steps below automatically. Use the manual steps if you need finer control or are integrating with an existing environment.

# Create and activate a virtual environment
python3.12 -m venv .venv
source .venv/bin/activate        # Windows: .\.venv\Scripts\Activate.ps1

# Install Python dependencies
pip install -r requirements-dev.txt

# Install Node dependencies for Tailwind (optional)
cd theme/static_src && npm install && cd ../..

Database

The default development configuration uses SQLite — no database server required.

python manage.py migrate
python manage.py seed_taxonomy
SCD_INITIAL_ADMIN_PASSWORD=yourpassword python manage.py seed_admin

Run the development server

python manage.py runserver

The app is available at http://localhost:8000. Log in with scd-admin@fnal.gov and your chosen password.

The development settings (scd_reporting.settings.dev) enable DEBUG=True, load Tailwind from the Play CDN, and log emails to the console.

For CSS hot-reload during frontend work, run cd theme/static_src && npm start in a second terminal.

AI Summary

To enable the AI Summary feature, export your Anthropic API key before starting the server:

export ANTHROPIC_API_KEY=sk-ant-...          # Windows: $env:ANTHROPIC_API_KEY="sk-ant-..."
python manage.py runserver

Without the key the summary button returns an error in the UI; all other features work normally. Obtain a key at console.anthropic.com.

To use a different model:

export ANTHROPIC_SUMMARY_MODEL=claude-haiku-4-5-20251001   # faster / cheaper

The default is claude-sonnet-4-6.

---

Running Tests

# Run the full test suite
.venv/bin/pytest tests/

# Run with coverage
.venv/bin/pytest tests/ --cov=apps --cov-report=term-missing

# Run a single test module
.venv/bin/pytest tests/test_entries.py -v

Tests use scd_reporting.settings.dev and SQLite in-memory (via pytest-django). No external services are required.

Current baseline: 87 tests, all passing.

---

Docker Deployment

See docs/deploy-docker.md for the full guide.

Quick start:

cp .env.example .env
# Edit .env — set POSTGRES_PASSWORD, DJANGO_SECRET_KEY, SCD_INITIAL_ADMIN_PASSWORD, SCD_HOSTNAME
docker compose up -d

---

User Roles

Role	Description	Permissions
User	Regular SCD staff	Submit and manage their own entries; view their own dashboard
Administrator	SCD managers	All User permissions + manage taxonomy (projects, categories, groups), reset/delete user accounts, view all entries, run reports, generate AI summaries, configure AI prompts, view audit log
Auditor	Read-only oversight	View all entries, run reports, generate AI summaries, view audit log — no write access

Role assignment is done via the Admin Users page (/admin-users/) by an Administrator.

---

URL Reference

Path	View	Access
/	Dashboard	Authenticated
/accounts/login/	Login	Public
/accounts/signup/	Sign up	Public (can be disabled)
/profile/	Edit profile	Authenticated
/admin-users/	User management	Admin
/admin-users/<pk>/set-password/	Reset a user's password	Admin
/admin-users/<pk>/delete/	Delete a user account	Admin
/taxonomy/projects/	Manage projects	Admin
/taxonomy/categories/	Manage categories	Admin
/taxonomy/groups/	Manage organisational groups	Admin
/entries/	My entries list	Authenticated
/entries/new/	Create entry	Authenticated
/entries/<pk>/	Entry detail	Entry owner
/entries/<pk>/edit/	Edit entry	Entry owner
/entries/<pk>/delete/	Delete entry	Entry owner
/reports/	Report filter, preview, export, AI summary	Admin / Auditor
/reports/preview/	HTMX preview partial (POST)	Admin / Auditor
/reports/download/<fmt>/	File download (txt csv json xlsx pdf)	Admin / Auditor
/reports/summary/	Generate AI summary (POST, HTMX)	Admin / Auditor
/reports/summary/download/txt/	Download AI summary as plain text	Admin / Auditor
/reports/summary/download/pdf/	Download AI summary as PDF	Admin / Auditor
/reports/prompt-config/	Save AI prompt configuration (POST)	Admin
/audit/	Audit log viewer	Admin / Auditor
/admin/	Django admin	Superuser

---

Environment Variables

All variables are loaded via .env in Docker Compose. For local development, export them in your shell or prefix the management command.

Required in production

Variable	Description
DJANGO_SECRET_KEY	Django cryptographic key — generate with python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
POSTGRES_PASSWORD	PostgreSQL password
SCD_INITIAL_ADMIN_PASSWORD	Password for the initial admin account created by seed_admin

Optional / have defaults

Variable	Default	Description
DJANGO_ALLOWED_HOSTS	localhost	Comma-separated list of valid Host header values
DATABASE_URL	sqlite:///db.sqlite3	Full database connection URL (dj-database-url format)
POSTGRES_DB	scd	PostgreSQL database name
POSTGRES_USER	scd	PostgreSQL user
DJANGO_SETTINGS_MODULE	(set explicitly)	Use scd_reporting.settings.prod in production
GUNICORN_WORKERS	3	Number of Gunicorn worker processes
SCD_HOSTNAME	localhost	Hostname Caddy listens on (enables automatic HTTPS for real domains)
SCD_INITIAL_ADMIN_USERNAME	scd-admin	Username of the bootstrapped admin
SCD_INITIAL_ADMIN_EMAIL	scd-admin@fnal.gov	Email of the bootstrapped admin
SCD_DISABLE_LOCAL_SIGNUP	0	Set to 1 to block new local accounts (for SSO-only deployments)
ACCOUNT_EMAIL_VERIFICATION	optional	allauth email verification mode: none, optional, or mandatory
ANTHROPIC_API_KEY	(empty)	API key for the Anthropic AI summary feature. Required to use AI Summary; the feature is silently disabled if unset. Obtain from console.anthropic.com.
ANTHROPIC_SUMMARY_MODEL	claude-sonnet-4-6	Anthropic model used for report summaries. Override to use a different model (e.g. claude-haiku-4-5-20251001 for faster/cheaper generation).

---

Management Commands

seed_admin

Creates the initial administrator account. Idempotent — safe to run on every deployment.

python manage.py seed_admin

Reads SCD_INITIAL_ADMIN_USERNAME, SCD_INITIAL_ADMIN_EMAIL, and SCD_INITIAL_ADMIN_PASSWORD from the environment. If SCD_INITIAL_ADMIN_PASSWORD is unset, the command exits with a warning and creates nothing.

See docs/man/scd-seed-admin.1 for the full man page.

seed_taxonomy

Seeds the default set of projects and categories. Idempotent — safe to run repeatedly.

python manage.py seed_taxonomy

Creates the following if they do not already exist:

Projects: DUNE, NOvA, MicroBooNE, CMS, LSST

Categories: Scientific, Operations, Outreach, Training

Additional projects, categories, and organisational groups can be created through the web interface at /taxonomy/projects/, /taxonomy/categories/, and /taxonomy/groups/ (Admin role required).

See docs/man/scd-seed-taxonomy.1 for the full man page.