# SoftEngine — Software Engineering Best Practices Vault

A curated knowledge depot of high-level software engineering principles, patterns, and practices for building maintainable, scalable, and secure systems.

## Vault Structure

```
SoftEngine/
├── README.md                          # This file
├── Architecture/
│   ├── Design-Principles.md           # SOLID, DRY, KISS, YAGNI, coupling/cohesion
│   ├── Architectural-Styles.md        # Layered, Hexagonal, Clean, Onion, Microservices
│   ├── Domain-Driven-Design.md        # DDD strategic/tactical patterns, bounded contexts
│   ├── CQRS-Event-Sourcing.md         # Command Query Responsibility Segregation
│   └── Architecture-Decision-Records.md # ADR process and templates
├── Patterns/
│   ├── Design-Patterns.md             # GoF patterns, enterprise patterns
│   ├── Integration-Patterns.md        # API, messaging, event-driven patterns
│   ├── Resilience-Patterns.md         # Circuit breaker, retry, bulkhead, timeout
│   └── Concurrency-Patterns.md        # Threading, async, actor model
├── Testing/
│   ├── Test-Pyramid.md                # Unit, integration, E2E, contract testing
│   ├── Test-Driven-Development.md     # TDD cycle, red-green-refactor
│   ├── Testing-Strategies.md          # Property-based, mutation, chaos testing
│   └── Test-Organization.md           # Test structure, naming, fixtures
├── DevOps/
│   ├── CI-CD-Best-Practices.md        # Pipeline design, GitOps, deployment strategies
│   ├── Infrastructure-as-Code.md      # Terraform, Pulumi, cloud patterns
│   ├── Observability.md               # Logging, metrics, tracing, alerting
│   ├── Git-Workflow.md                # Branching, trunk-based, feature flags
│   └── Release-Management.md          # Versioning, rollback, progressive delivery
├── Security/
│   ├── Secure-Coding.md               # OWASP top 10, secure coding practices
│   ├── Authentication-Authorization.md # AuthN/AuthZ, OAuth, OIDC, RBAC/ABAC
│   ├── Cryptography.md                # Encryption, hashing, key management
│   ├── API-Security.md                # REST/gRPC security, rate limiting
│   └── Supply-Chain-Security.md       # SBOM, dependency scanning, signing
├── Performance/
│   ├── Performance-Engineering.md     # Methodology, objectives, budgeting
│   ├── Profiling-Optimization.md      # Hot paths, code optimization, memory
│   ├── Caching-Strategies.md          # Cache patterns, invalidation, CDN
│   ├── Database-Optimization.md       # Indexing, query tuning, sharding
│   └── Concurrency-Scaling.md         # Thread pools, async, horizontal scaling
├── Documentation/
│   ├── Documentation-Principles.md    # Diátaxis, README, API docs
│   ├── Architecture-Decision-Records.md # ADR templates, process
│   ├── Technical-Writing.md           # Style, clarity, audience awareness
│   └── Knowledge-Management.md        # Wikis, runbooks, onboarding
├── Tools/
│   ├── Developer-Tools.md             # IDE, debugging, profiling, CLI
│   ├── Build-Tools.md                 # Bazel, Gradle, Maven, npm, Cargo
│   ├── Static-Analysis.md             # Linting, type checking, SAST
│   └── Package-Management.md          # Dependencies, lockfiles, registries
├── Languages/
│   ├── Language-Agnostic-Principles.md # Universal patterns across languages
│   ├── TypeScript-JavaScript.md       # Modern JS/TS patterns
│   ├── Python.md                      # Pythonic patterns, tooling
│   ├── Go.md                          # Go idioms, concurrency
│   ├── Rust.md                        # Ownership, borrowing, async
│   └── JVM-Kotlin-Scala.md            # JVM ecosystem patterns
└── Methodologies/
    ├── Agile-Principles.md            # Agile manifesto, values, principles
    ├── Scrum-Guide.md                 # Roles, events, artifacts
    ├── Kanban-Method.md               # Flow, WIP, visualization
    ├── Extreme-Programming.md         # XP practices, values
    ├── Team-Topologies.md             # Team structures, interaction modes
    └── Engineering-Culture.md         # Blameless postmortems, learning org
```

## Quick Navigation by Concern

| If you're... | Start here |
|---|---|
| Designing a new system | `Architecture/Design-Principles.md` → `Architecture/Architectural-Styles.md` |
| Choosing patterns | `Patterns/Design-Patterns.md` → `Patterns/Integration-Patterns.md` |
| Setting up testing | `Testing/Test-Pyramid.md` → `Testing/Test-Driven-Development.md` |
| Building CI/CD | `DevOps/CI-CD-Best-Practices.md` → `DevOps/Git-Workflow.md` |
| Securing an application | `Security/Secure-Coding.md` → `Security/Authentication-Authorization.md` |
| Optimizing performance | `Performance/Performance-Engineering.md` → `Performance/Profiling-Optimization.md` |
| Documenting decisions | `Documentation/Architecture-Decision-Records.md` |
| Improving team process | `Methodologies/Agile-Principles.md` → `Methodologies/Team-Topologies.md` |

## Principles That Cross-Cut All Categories

1. **Manage dependencies / control coupling** — from class-level DI to service boundaries to vendor risk
2. **Optimize for change** — small functions, extensible design, tests that enable refactoring, small deploys
3. **Fail fast and safely** — surface errors early, fail into safe states, test recovery before you need it
4. **Simplicity is a feature** — YAGNI/KISS, start with monolith, don't reach for Kubernetes prematurely
5. **Automate the repeatable** — formatters, linters, CI/CD, dependency scanning, evidence collection
6. **Learn without blame** — blameless post-mortems, regression tests for every bug, critique code not people
7. **If it isn't written down, it didn't happen** — commit messages, ADRs, explicit risk acceptance, visible tech debt
8. **Failure is the normal case** — timeouts, idempotent retries, rollback-ready deploys, error budgets

## Contributing

This vault is a living document. When you discover a valuable practice, pattern, or principle:
1. Find the relevant category folder
2. Create or update the appropriate `.md` file
3. Link related notes with `[[Wikilinks]]`
4. Keep entries practical and actionable — prefer concrete guidance over theory

---

*Curated from industry-leading sources: OWASP, Martin Fowler, AWS/GCP/Azure Well-Architected, Google SRE, Microsoft Patterns & Practices, Thoughtworks, and community best practices.*