camera

CammyCam Contributor Guide

This document outlines the workflow and style guidelines for contributing to the CammyCam firmware, backend, and UI.

---

✈️ Documentation Pages

Page	Description
What Sets it Apart	Unique features and DIY cost breakdown
MVP	High-level project goals and summary
Status Tracker	Feature progress overview
Unit Testing	Testing instructions and coverage details
Firmware	Firmware API reference
Build It Yourself	Clone & Docker setup guide
Hub Guide	Hub API documentation
Communication Methods	System communication architecture

---

Repo Layout

• esp/esp32-cammycam/ – PlatformIO firmware
• ui/ – Vite + Vue 3 frontend
• pi/ – FastAPI hub backend
• docs/ – Project documentation
• docs/styleguide.md – Cozy Cabin UI color palette

---

Documentation Consistency

• Maintain consistent terminology across documentation (e.g., “Ad-hoc AP Mode,” “Wi-Fi Client Mode,” “Hub Mode”).
• Update documentation immediately upon making code or architectural changes.
• Perform periodic checks using scripts or linters to enforce documentation consistency.

---

Coding Style

C++

• 4-space indents.
• Opening braces on the same line.
• Use snake_case for names.
• Spaces around operators and commas.
• Doc comments above functions.
• Named constants/enums instead of magic numbers.
• Include guards or #pragma once in headers.

TypeScript/Vue

• 2-space indents, no semicolons.
• Use camelCase naming.
• Explicit types/interfaces for props, emits, data.
• Follow Cozy Cabin colors strictly.

Python

• Python 3.10+, follow PEP8 and Black formatting.
• Mandatory docstrings.
• Type hints (mypy, pyright).
• Document endpoints clearly.
• Secrets via environment variables.

---

• Keep docs/glossary.md in sync with any new terminology introduced.

  Testing

• Ensure all commands (pio test, pytest -q, npm run build) finish cleanly in fresh environments.
• Document .env requirements clearly.
• Deterministic tests only.

---

Pull Requests

• Concise, descriptive summaries.
• Include relevant test results.
• Reference issues and docs clearly.
• One feature/fix per PR.

---

Commit Guidelines

• Small, focused commits with clear messages.
• LF endings enforced.

---

Security Standards

• Data in transit via TLS only.
• Passwords and secrets hashed and salted.
• Require authentication for protected endpoints.

---

Ongoing Responsibilities

• Review latest commits and PR comments regularly.
• Synchronize README files, documentation, and inline comments with implementation.
• Resolve mismatches between code and documentation promptly.

---

Agent Awareness and Change Tracking

• Agents must check recent commits, open PRs, and implementation versus documentation mismatches before updates.

---

AI Assistant Instruction Files

Use AGENTS.md as canonical source for engineering rules. Tool-specific files map back to this document so behavior stays consistent across assistants:

• .github/copilot-instructions.md (GitHub Copilot)
• .github/instructions/*.instructions.md (path-scoped Copilot rules for firmware, UI, backend)
• CLAUDE.md (Claude)
• CODEX.md (Codex/OpenAI agents)
• GEMINI.md (Gemini)

When updating development standards, update AGENTS.md first, then synchronize tool-specific files.

---

SPIFFS UI Requirements

• Minimal SPIFFS UI matching style guide.
• Provide essential features (MJPEG stream, config options, storage info, pairing button).

---

Versioning & Changelog Sync

• Update CHANGELOG.md for new features and reference status tracker updates.
• Avoid duplication between CHANGELOG.md and status_tracker.md.

---

Scripting Standard

• Python preferred for cross-platform and complex scripts.
• Shell scripts only for minimal, OS-agnostic tasks.