camera

CammyCam Contributor Guide

Current Version

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.

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.