---

date: 2025.12.29
tags: [SoftwareEngineering, BetaSprint, CodeStandards, StudentSys]

Project entry: http://159.75.26.213
This post defines our team’s coding and collaboration standards for the Beta stage, so we can reduce integration bugs, avoid “works on my machine” failures, and make deployment reproducible.

---

1. Why We Need Code Standards (Lessons from Alpha)

During Alpha, many problems were not caused by “hard algorithms”, but by:

• inconsistent endpoints and route prefixes

• environment variables not synchronized or not loaded by the running process

• ad-hoc server edits without PR review

• unclear ownership (“everyone fixes everything”)

So in Beta we enforce standards to make our work repeatable, reviewable, and deployable.

---

2. Repository Structure (Single Source of Truth)

We keep a clear top-level structure so every member knows where to work.

Recommended layout

StudentSys/
  backend/                 # Node.js/Express REST API
  frontend/                # Web UI
  python_services/         # FastAPI services (face/takeout/crowd/traffic)
  docs/                    # API + deployment + conventions
  scripts/                 # health checks, setup helpers
  infra/                   # nginx/systemd/pm2 config templates
  README.md
  .env.example

Rules

• No “random” files at root except repo-wide configs and README.

• Anything deployment-related must be tracked in docs/ + infra/.

• A new module must include:

  • code folder

  • minimal README

  • known ports/endpoints documented in docs/

---

3. Branching Strategy (Simple & Enforceable)

We use a lightweight Git flow suitable for course projects.

• main: always demo-ready (stable, runnable)

• dev: integration branch for ongoing work (optional if team prefers main-only with PRs)

• feature/<module>-<short-desc>: new features

• fix/<bug>-<short-desc>: bugfixes

• docs/<topic>: documentation-only changes

Rules

• Never push directly to main.

• All merges to main must go through PR + review.

• Hotfix allowed only when demo is blocked, but still via PR.

---

4. Issue Workflow (Everything Non-trivial Has an Issue)

For Beta sprint blogs, dev progress must be backed by Issues/PRs. We standardize that here.

Issue must include

• Title: [Module] short description

• Background / expected behavior

• Acceptance criteria (how we know it’s done)

• Labels: frontend, backend, ai-service, docs, bug, enhancement, deployment

• Assignee + estimated effort (small/medium/large)

Definition of Done

• Code merged via PR

• Basic local test passed

• Endpoint/docs updated if interface changed

• Screenshot/log evidence if required by sprint blog

---

5. Pull Request (PR) Rules

PRs are not optional—they are our safety net.

PR title format

• feat(frontend): ...

• fix(backend): ...

• docs: ...

• chore(deploy): ...

PR description must include

• What changed and why

• Linked Issues: Closes #123

• Test evidence: how you verified (commands + screenshots where needed)

• Deployment impact: does this require env/nginx/systemd updates?

Minimal review checklist

• Code compiles/runs

• No secrets committed

• Routes/endpoints match docs

• Error handling is user-friendly (not raw stack traces)

• Logging added for key operations

• No breaking changes without notice

Optional evidence placeholder for blog:
[IMG_PLACEHOLDER: PR_review_screenshot.png]

---

6. Commit Message Convention

We use conventional commits to keep history readable and searchable.

Format

• feat: add takeout detection UI

• fix: correct DB env loading

• refactor: simplify router structure

• docs: update deployment checklist

• chore: update dependencies

Rules

• One commit = one logical change (avoid mixing unrelated changes)

• Commit early and often, but don’t commit broken builds to shared branches

---

7. Backend Standards (Node.js / Express)

7.1 API Design

• All backend routes must be under a consistent prefix, e.g. /api/...

• Add health check endpoint (backend): /api/health

• Use consistent JSON response format:

Success

{ "code": 0, "message": "ok", "data": { ... } }

Error

{ "code": 1001, "message": "Invalid input", "hint": "Check email format", "data": null }

7.2 Error Handling

• Never return raw stack traces to frontend

• Log the internal error; return a user-friendly message

7.3 Configuration

• All sensitive config must come from environment variables

• Backend must fail fast with clear log output if env is missing

---

8. Database Standards (MySQL/MariaDB)

• Use least privilege DB user for runtime (not root)

• DB migrations/initialization must be documented:

  • schema changes

  • required tables

  • seed data (if any)

• Changes that break schema require:

  • a short migration note in docs/DEPLOYMENT.md

  • coordination with backend owners

---

9. Python AI Services Standards (FastAPI/Uvicorn)

We have multiple services (face/takeout/crowd/traffic). Consistency matters.

9.1 Health Endpoints

Every service must expose:

• /health (returns 200 + simple JSON)

When proxied by Nginx, external access should be consistent:

• /api/face/health

• /api/takeout/health

• /api/crowd/health

• /api/traffic/health

9.2 Dependency Rules

• requirements.txt must be platform-neutral (no Windows wheels)

• System dependencies (e.g., OpenCV runtime libs) must be listed in docs/DEPLOYMENT.md

9.3 Runtime Rules

• CPU-first by default (GPU only if infrastructure confirmed)

• Add warm-up strategy if cold start is slow

• Log request info and inference timing (p50/p95 later if possible)

---

10. Frontend Standards

10.1 UI Consistency

• Use consistent navigation labels and page layout spacing

• Forms must validate input and show actionable errors

10.2 API Integration

• Centralize API base URL and request wrapper

• Handle common error codes:

  • 401/403: show login prompt

  • 404: show “feature not available / wrong route”

  • 500: show “system busy, try again” with retry suggestion

---

11. Documentation Rules

Docs are part of the deliverable, not optional.

Must-have docs

• docs/DEPLOYMENT.md

  • ports

  • env variables

  • system packages

  • restart commands (pm2/systemd)

  • nginx routing notes

• docs/API.md

  • routes + request/response examples

  • error codes

Rule

• If you change an endpoint, you must update docs/API.md in the same PR.

---

12. Testing & Quality Baseline (Minimum Standard)

We keep it minimal but effective.

Required

• A simple “health check script” (bash) that curls all services

• Smoke test steps recorded in sprint blog (screenshots or terminal output)

Recommended

• ESLint/Prettier for frontend/backend formatting

• Python formatting tool (e.g., black) if feasible

---

13. Deployment Discipline (No More “Edit on Server”)

Rule

• No direct editing on production server without PR

• Deployment changes must be recorded:

  • update infra/ configs

  • document in docs/DEPLOYMENT.md

Standard deployment checklist

• env check → DB check → service status check → health check → public access check

---

14. Ownership & Communication

To avoid duplicated work and missing tasks, we define module owners:

• Backend owner: API + DB integration

• Frontend owner: UI + integration

• Deployment owner: Nginx + pm2/systemd + env

• AI services owner: FastAPI services

If a change impacts another module, it must be communicated in Issue/PR description.

---

15. Conclusion

These standards are designed to reduce integration failures, increase collaboration efficiency, and make our Beta sprint outputs reviewable and demo-ready. In the next sprint blogs, we will enforce evidence-based reporting (Issues/PRs/results) and keep documentation synchronized with code changes.