ENGINEERING STANDARDS

> cat ./standards/engineering_philosophy.md

This is the living document that governs how I build software. Every project I work on starts with these principles. They aren't theoretical — they're the same standards applied to this site, enforced in CI, and visible in every commit.

01 // CLEAN ARCHITECTURE & DESIGN
  • > API contracts are sacred. Define them first, implement second.
  • > Simplicity wins. If it's hard to explain, it's probably wrong.
  • > Separation of concerns is non-negotiable. Business logic never leaks into transport layers. Data models never bleed across bounded contexts.
  • > Documentation is part of the deliverable, not an afterthought.
  • > Design for the interface, not the implementation.
02 // TEST-DRIVEN DEVELOPMENT
  • > Tests come first. Always. No exceptions.
  • > If it isn't tested, it doesn't exist.
  • > Tests are first-class citizens. Same quality standards as production code.

COVERAGE EXPECTATIONS:

Unit tests Integration tests Regression tests Smoke tests Contract tests Edge cases & boundaries
03 // DON'T REPEAT YOURSELF
  • > Every piece of knowledge has one authoritative source.
  • > DRY applies to: code, configuration, documentation, test fixtures, data schemas, and API definitions.
  • > Caveat: DRY does not mean premature abstraction. Two instances may be coincidence. Three is a pattern. Abstract on three.
04 // DATA MODELING & ARCHITECTURE
  • > Access pattern drives schema design. Write-heavy: normalize (3NF/BCNF). Read-heavy: denormalize (Kimball).
  • > Kimball Dimensional Modeling is the default for analytical models. Star schema baseline, snowflake when hierarchy depth justifies join cost.
  • > OLTP and OLAP are separate concerns. Separate schemas, separate roles, separate access patterns.
  • > Schema changes are versioned migrations, never manual edits. Data contracts apply — downstream consumers must not break from upstream changes.
05 // SECURITY & CRYPTOGRAPHY
  • > Security is phase 0, not phase 2.
  • > Post-Quantum Cryptography readiness is a first-class concern. Target CRYSTALS-Kyber (ML-KEM), CRYSTALS-Dilithium (ML-DSA), SHA-3/SHAKE.
  • > Crypto agility is mandatory. No algorithm hardcoded. Cipher suites, key sizes, and identifiers must be configurable and swappable.
  • > Security scanning is infrastructure: SAST, SCA, secret scanning, container scanning — on every commit.

CVE RESPONSE SLA:

CRITICAL: before next merge HIGH: this sprint MEDIUM: tracked LOW: triaged & documented
06 // DEPENDENCY MANAGEMENT
  • > Pin versions exactly. No floating specifiers. Lock files are committed and treated as source artifacts.
  • > Every new dependency is a liability. Justify it. Document it. Audit regularly for staleness, abandonment, and CVEs.
  • > Circular dependencies are bugs. Detect in CI, fail the build.
07 // TECHNOLOGY SOVEREIGNTY
  • > Open-source, self-hostable solutions are the default.
  • > No runtime dependency on big-tech hosted services. Their OSS projects evaluated on technical merit only.
  • > Self-deployment capability is mandatory. Docker Compose for local dev, container-orchestration-ready for production.
08 // PROGRAMMATIC EFFICIENCY
  • > Algorithmic complexity is a design concern, not an optimization concern. Always know the complexity.
  • > O(1) > O(log n) > O(n) > O(n log n) > O(n²). Verify no better alternative exists before accepting worse complexity.
  • > Premature optimization is still a sin. Design before profiling. But flag O(n²) or worse.
09 // CODE QUALITY & ANNOTATION
  • > Readable by a stranger in 6 months. Functions do one thing.
  • > No magic numbers or strings — named constants with clear origin.
  • > Error handling is explicit. Silent failures are bugs.

INLINE ANNOTATION TAGS:

// TECH DEBT:Shortcut, needs resolution
// PERF:Performance concern
// SECURITY:Security-sensitive, review carefully
// PQC DEBT:Classical crypto, needs migration
// FIXME:Broken, must fix before release
// SCHEMA:Fragile if schema changes
// VENDOR LOCK-IN:Vendor dependency, needs escape path
// DEPENDENCY RISK:Stale or under-maintained dep
10 // CONVENTIONAL COMMITS

Write the subject line in the imperative mood. Imagine the phrase completes: "If applied, this commit will..."

<type>(optional scope): short summary
feat:New feature or capability
fix:Bug fix
docs:Documentation-only changes
refactor:Neither fix nor feature
perf:Performance improvement
test:Adding or correcting tests
chore:Routine tasks, build processes
style:Formatting changes

EXAMPLES:

Backend: feat(api): add patient redaction endpoint

Data: fix(etl): resolve timestamp anomaly in incremental load

Frontend: refactor(ui): extract vaporwave button into reusable component

11 // DOCUMENTATION & ISSUE TRACKING
  • > READMEs evolve with the code, not written after. Required: quickstart, config reference, architecture overview, testing, deployment, troubleshooting.
  • > The Minimal Working Example is non-negotiable. Runnable in under 10 minutes using only the README.
  • > Bugs that consume 1+ hour of debugging get documented. Format: Date, Environment, Symptoms, Root Cause, Fix, Prevention.
  • > Three or more similar issues = architectural smell. Escalate to an Architecture Decision Record.
12 // PREFERRED PATTERNS & IDIOMS
> Hexagonal Architecture (Ports & Adapters)
> Repository Pattern — data access abstracted
> Strategy Pattern — behaviors swappable
> Factory / Builder — readable object creation
> CQRS — separate read/write when justified
> Event-driven — decoupling across contexts
> Kimball Dimensional Modeling (star default)
> Dependency Injection over hard dependencies