# Stack Overview

Development philosophy and code standards.

## Lean code

Minimum code that delivers direct value.

- **YAGNI**: Don't implement "just in case"
- **DRY**: Don't repeat, but don't over-abstract
- **KISS**: The simplest thing that works

## Coding style

- Avoid obvious comments. Self-explanatory code.
- Avoid redundant docs. Clear names.
- Avoid premature abstraction. Direct code.
- Avoid trivial tests. Test behavior.
- One module = one responsibility. Short files (50–100 lines).

---

## API versioning

Every API must follow semantic versioning.

### Rules

- **PATCH** (0.1.X): Bug fixes, minor changes
- **MINOR** (0.X.0): New endpoints, new features
- **MAJOR** (X.0.0): Breaking changes

### Workflow before deploy

1. Bump the version in Cargo.toml / package.json
2. Commit with message: `rel: vX.Y.Z - description`
3. Deploy
4. Verify: `curl https://api.example.com/v1/health`

---

## Health endpoints

Every service exposes `/health` or `/v1/health`.

### Mandatory JSON shape

    {
        "message": "API is running",
        "version": "0.2.0",
        "build_time": "2026-01-25T22:35:00Z",
        "timestamp": "2026-01-25T22:35:15.123456+00:00"
    }

### Fields

- **version**: Version from Cargo.toml / package.json (compile time)
- **build_time**: Build timestamp (compile time)
- **timestamp**: Current server time (runtime)

### Implementation per stack

**Backend (Rust)**:

    // build.rs — emits BUILD_TIME at compile time
    println!("cargo:rustc-env=BUILD_TIME={}", timestamp);

    // health.rs
    env!("CARGO_PKG_VERSION")  // version
    env!("BUILD_TIME")          // build_time

**Frontend (SolidJS)**: public/health.json generated at build time
**Frontend (Next.js)**: /api/health reading package.json

---

## Release system (Git tags)

Each service keeps stable releases marked with git tags.

### When to cut a release

- After deploying significant changes to production
- When the system is verified and stable
- Before starting refactors or large changes

### Tag format

```
v<major>.<minor>.<patch>

Examples:
- v1.0.0  → First stable release
- v1.0.12 → Patch 12 of the 1.0 line
- v1.1.0  → New feature added
- v2.0.0  → Breaking changes
```

### Commands

```bash
# Cut a release for the current commit
git tag -a v1.0.12 -m "Stable release - description"
git push origin v1.0.12

# Cut a release for a previous commit
git tag -a v1.0.12 <commit_hash> -m "Stable release"
git push origin v1.0.12

# List every release
git tag

# Roll back to a release
git checkout v1.0.12

# Diff since a release
git diff v1.0.12..HEAD
```

### Workflow

```
Develop → Commits → Deploy → Verify → TAG RELEASE
              ↑                            ↓
              └──── more development ──────┘
```

### Per service

Each repo (api, pulse, broker, master) keeps its own independent tags.

---

See subfolders for layer-specific details.