init commit

docs/code_guidelines.md

@@ -0,0 +1,120 @@
+### 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:
+
+```json
+{
+  "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**