weather-alerts/docs/code_guidelines.md

Coding Standards

Style & Structure

• Prefer longer, explicit code over compact one-liners
• Always include docstrings for functions/classes + inline comments
• Strongly prefer OOP-style code (classes over functional/nested functions)
• Strong typing throughout (dataclasses, TypedDict, Enums, type hints)
• Value future-proofing and expanded usage insights

Data Design

• Use dataclasses for internal data modeling
• Typed JSON structures
• Functions return fully typed objects (no loose dicts)
• Snapshot files in JSON or YAML
• Human-readable fields (e.g., scan_duration)

Templates & UI

• Don't mix large HTML/CSS blocks in Python code
• Prefer Jinja templates for HTML rendering
• Clean CSS, minimal inline clutter, readable template logic

Writing & Documentation

• Markdown documentation
• Clear section headers
• Roadmap/Phase/Feature-Session style documents
• Boilerplate templates first, then refinements

Logging

• Use structlog (pip package)
• Setup logging at app start: logger = logging.get_logger(__file__)

Preferred Pip Packages

• API/Web Server: Flask
• HTTP: Requests
• Logging: Structlog
• Scheduling: APScheduler

Error Handling

• Custom exception classes for domain-specific errors
• Consistent error response formats (JSON structure)
• Logging severity levels (ERROR vs WARNING)

Configuration

• Each component has environment-specific configs in its own /config/*.yaml
  • API: /api/config/development.yaml, /api/config/production.yaml
  • Web: /public_web/config/development.yaml, /public_web/config/production.yaml
• .env for secrets (never committed)
• Maintain .env.example in each component for documentation
• Typed config loaders using dataclasses
• Validation on startup

Containerization & Deployment

• Explicit Dockerfiles
• Production-friendly hardening (distroless/slim when meaningful)
• Clear build/push scripts that:
  • Use git branch as tag
  • Ask whether to tag :latest
  • Ask whether to push
  • Support private registries

API Design

• RESTful conventions
• Versioning strategy (/api/v1/...)
• Standardized response format:

{
  "app": "<APP NAME>",
  "version": "<APP VERSION>",
  "status": <HTTP STATUS CODE>,
  "timestamp": "<UTC ISO8601>",
  "request_id": "<optional request id>",
  "result": <data OR null>,
  "error": {
    "code": "<optional machine code>",
    "message": "<human message>",
    "details": {}
  },
  "meta": {}
}

Dependency Management

• Use requirements.txt and virtual environments (python3 -m venv venv)
• Use path venv for all virtual environments
• Pin versions to version ranges
• Activate venv before running code (unless in Docker)

Testing Standards

• Manual testing preferred for applications
• API Backend: Maintain api/docs/API_TESTING.md with endpoint examples, curl/httpie commands, expected responses
• Unit tests: Use pytest for API backend (api/tests/)
• Web Frontend: If using a web frontend, Manual testing checklist are created in public_web/docs

Git Standards

Branch Strategy:

• master - Production-ready code only
• dev - Main development branch, integration point
• beta - (Optional) Public pre-release testing

Workflow:

• Feature work branches off dev (e.g., feature/add-scheduler)
• Merge features back to dev for testing
• Promote dev → beta for public testing (when applicable)
• Promote beta (or dev) → master for production

Commit Messages:

• Use conventional commit format: feat:, fix:, docs:, refactor:, etc.
• Keep commits atomic and focused
• Write clear, descriptive messages

Tagging:

• Tag releases on master with semantic versioning (e.g., v1.2.3)
• Optionally tag beta releases (e.g., v1.2.3-beta.1)

---

Workflow Preference

I follow a pattern: brainstorm → design → code → revise