Development

.env.example

@@ -1,45 +1,81 @@
+# Application metadata and runtime environment.
 APP_NAME=Todo Modulith API
 APP_ENV=production
+FRONTEND_URL=http://localhost:3000
 
+# Local service credentials used by Docker Compose.
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=
 POSTGRES_DB=todo_db
 REDIS_PASSWORD=
 
+# Database connection string and SQLAlchemy pool tuning.
 DATABASE_URL=
 DATABASE_POOL_SIZE=20
 DATABASE_MAX_OVERFLOW=10
 DATABASE_POOL_TIMEOUT=30
 DATABASE_POOL_RECYCLE=3600
 
+# Redis connection used by shared infrastructure such as rate limiting or caching.
 REDIS_URL=
 
+# JWT signing secret. Change this in every deployed environment.
 SECRET_KEY=
 
+# Maximum request body size in bytes.
 MAX_REQUEST_SIZE_MB=5242880 #5mb
 
+# JWT signing, validation, and token lifetime settings.
 ALGORITHM=HS256
 JWT_ISSUER=todo-modulith-api
 JWT_AUDIENCE=todo-modulith-client
 ACCESS_TOKEN_EXPIRE_MINUTES=30
 REFRESH_TOKEN_EXPIRE_MINUTES=10080
 
+# API rate limit rule.
 RATE_LIMIT="100/minute"
 
+# CORS settings for browser clients.
 CORS_ALLOW_ORIGINS=http://localhost:3000
 CORS_ALLOW_METHODS=*
 CORS_ALLOW_HEADERS=*
 
+# Content Security Policy header value.
 SECURITY_CONTENT_SECURITY_POLICY=default-src 'self'; frame-ancestors 'none'
 
+# Idempotency key retention time in seconds.
 IDEMPOTENCY_TTL_SECONDS=86400
 
+# Account lockout thresholds used to slow repeated failed login attempts.
 ACCOUNT_LOCKOUT_MAX_ATTEMPTS=5
 ACCOUNT_LOCKOUT_WINDOW_MINUTES=15
 ACCOUNT_LOCKOUT_DURATION_MINUTES=15
 
+# Logging output format for application logs.
 LOG_FORMAT=json
 
+# Email provider selection. Options: ses, sendgrid, smtp.
+EMAIL_PROVIDER=ses
+
+# AWS SES configuration.
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+SES_FROM_EMAIL=noreply@example.com
+
+# SendGrid configuration.
+SENDGRID_API_KEY=
+SENDGRID_FROM_EMAIL=noreply@example.com
+
+# SMTP configuration for Gmail or other SMTP providers.
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_FROM_EMAIL=noreply@example.com
+SMTP_USE_TLS=true
+
+# Optional admin and development users created by database seeders.
 SEED_ADMIN_EMAIL=
 SEED_ADMIN_PASSWORD=
 SEED_ADMIN_USERNAME=admin

.gitignore

@@ -1,21 +1,23 @@
-# Poetry specific files
-.venv/
-/dist/
-/poetry.toml
-
-# Python bytecode and caches
-__pycache__/
+```
 *.pyc
-*.pyo
-*.pyd
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-.cache/
-
-# Environment variables (secret keys)
+__pycache__/
+*.log
+*.tmp
+*.swp
 .env
-
-# IDE settings
+.env.local
+.env.*
 .vscode/
 .idea/
+dist/
+build/
+target/
+.venv/
+venv/
+node_modules/
+.mypy_cache/
+.pytest_cache/
+.coverage
+coverage/
+htmlcov/
+```

.importlinter

@@ -0,0 +1,50 @@
+[importlinter]
+root_package = src
+
+[importlinter:contract:todo-cross-module-boundary]
+name = Todo module only imports public contracts from other modules
+type = forbidden
+allow_indirect_imports = True
+source_modules =
+    src.modules.todo
+forbidden_modules =
+    src.modules.user.application
+    src.modules.user.domain
+    src.modules.user.infrastructure
+    src.modules.user.presentation
+    src.modules.authorization.application
+    src.modules.authorization.domain
+    src.modules.authorization.infrastructure
+    src.modules.authorization.presenter
+
+[importlinter:contract:user-cross-module-boundary]
+name = User module only imports public contracts from other modules
+type = forbidden
+allow_indirect_imports = True
+source_modules =
+    src.modules.user
+forbidden_modules =
+    src.modules.todo.application
+    src.modules.todo.domain
+    src.modules.todo.infrastructure
+    src.modules.todo.presentation
+    src.modules.authorization.application
+    src.modules.authorization.domain
+    src.modules.authorization.infrastructure
+    src.modules.authorization.presenter
+
+[importlinter:contract:authorization-cross-module-boundary]
+name = Authorization module only imports public contracts from other modules
+type = forbidden
+allow_indirect_imports = True
+source_modules =
+    src.modules.authorization
+forbidden_modules =
+    src.modules.todo.application
+    src.modules.todo.domain
+    src.modules.todo.infrastructure
+    src.modules.todo.presentation
+    src.modules.user.application
+    src.modules.user.domain
+    src.modules.user.infrastructure
+    src.modules.user.presentation

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: local
+    hooks:
+      - id: import-linter
+        name: import-linter
+        entry: poetry run lint-imports
+        language: system
+        pass_filenames: false

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:poetry",
+    "python-envs.defaultPackageManager": "ms-python.python:poetry"
+}

Makefile

@@ -3,21 +3,23 @@ SHELL := /bin/bash
 PYTHON := .venv/bin/python
 PYTEST := .venv/bin/pytest
 RUFF := .venv/bin/ruff
+IMPORT_LINTER := .venv/bin/lint-imports
 UVICORN := .venv/bin/uvicorn
 ALEMBIC := .venv/bin/alembic
 POETRY := poetry
 COMPOSE_FILE := docker-compose.yml
 
 .DEFAULT_GOAL := help
 
-.PHONY: help install run test lint import-check security-scan check migrate seed downgrade revision db-up db-down db-logs clean
+.PHONY: help install run test lint lint-imports import-check security-scan check migrate seed downgrade revision db-up db-down db-logs clean
 
 help:
 	@echo "[make:help] Available commands:"
 	@echo "  [make:install]       Install project dependencies with Poetry"
 	@echo "  [make:run]           Run the FastAPI development server"
 	@echo "  [make:test]          Run pytest"
 	@echo "  [make:lint]          Run Ruff checks"
+	@echo "  [make:lint-imports]  Enforce import boundary contracts"
 	@echo "  [make:import-check]  Verify src.main imports"
 	@echo "  [make:security-scan] Run dependency vulnerability scan with pip-audit"
 	@echo "  [make:check]         Run tests, lint, and import check"
@@ -46,6 +48,10 @@ lint:
 	@echo "[make:lint] Running Ruff checks"
 	@$(RUFF) check src tests scripts
 
+lint-imports:
+	@echo "[make:lint-imports] Enforcing import boundary contracts"
+	@$(IMPORT_LINTER)
+
 import-check:
 	@echo "[make:import-check] Verifying src.main imports"
 	@PYTHONDONTWRITEBYTECODE=1 $(PYTHON) -c "import src.main; print('import ok')"
@@ -54,7 +60,7 @@ security-scan:
 	@echo "[make:security-scan] Running dependency vulnerability scan"
 	@PIP_CACHE_DIR=.cache/pip $(POETRY) run pip-audit --cache-dir .cache/pip-audit
 
-check: test lint import-check
+check: test lint lint-imports import-check
 	@echo "[make:check] All checks completed"
 
 migrate: