# System Development Principles ## 1 Functional Independence Programming is modularized. Every module and every function works independently as long as environment and parameters are set properly. Every module and function has a comment section at the top that explains - what the module / function does - underlying assumptions and assertions for expected preconditions before this runs, and postconditions after - the input parameters - the output - API contracts (if applicable) ## 2 Keep it linear. No deep nesting. No hidden jumps. Code should read top to bottom like a well-constructed argument — premise, reasoning, conclusion. ## 3 Bound every loop. Every iteration needs a defined ceiling. Always ask: what is the maximum number of times this runs, and what happens when we hit it? ## 4 One function, one job. Each function should do exactly one thing. ## 5 Keep it short Principles 2, 3, and 4 implicate to keep functions short, not longer than 40 - 60 lines. When this limits is exeeded, analyse how a function can be decomposed and refactored (possibly in multiple separate functions). ## 6 Handle resources properly Every resource you open, you close. Every connection you borrow, you return. Resource lifetime must be declared, not assumed — and it must be correct on the error path too. Follow the code through every exit path and confirm it closes what it opened. ## 7 Error handling Every failure path must be handled, logged, or propagated. Distinguish between user-facing errors (toast/UI feedback) and developer-facing errors (console.error with context). ## 8 Narrow the state Scope data states locally and pass dependencies explicitly — make the data flow visible at every call site. ## 9 Keep abstractions direct and traceable After every generation, ask: can this be written more directly? Favour composition you can read linearly over elegance you have to decode. ## 10 Clearly state the side effects. I/O, mutations, and network calls should be obvious at the call site. Not hidden inside helpers, not wrapped in abstractions with innocent-looking names, not four layers deep in a chain of decorators. Instead: clear structural separation between pure computation and side-effectful operations. Dangerous stuff should be visible, named, and obvious. Document potential side effects in "docs/decisions/side-effects.md", organized by feature section. ## 11 Tests first Write the tests before — or alongside — the implementation that evaluates the expected and unexpected behaviour. Execute a test directly after coding. On failure: loop coding - testing - coding - testing until a function delivers the expected results also for edge cases. Do not only look at errors but also warnings as they can be tomorrow's errors. Share test results in the chat after each run. Maintain a test coverage map in "docs/logs/tests.md" documenting: - test strategy overview - what is tested successfully - what has failing tests (with brief reason) - what remains untested ## 12 Document the architecture Systems can grow complex. The primary architecture document is WORKSHOP_SYSTEM.md in the project root, covering system design, data model, dependencies, and architectural decisions. Keep it up to date as the system evolves. ## 13 Safety, security, and privacy by design ### Safety Design systems to default to a "safe state" if a crash occurs. Strictly sanitize all inputs to prevent unexpected behavior in downstream logic. For high-stakes decisions, ensure the code requires human verification before execution. ### Security Assign the minimum level of access required for any function or user to perform its task. Never assume a request is safe because it comes from an internal network. Authenticate and authorize every request. Where possible, use multiple layers of security (e.g., encryption + firewalls + MFA) so that the failure of one does not compromise the whole system. Avoid hardcoded credentials. Use environment variables and secret management vaults. ### Privacy Only collect, process, and retain the absolute minimum amount of personal data necessary for the specific feature. Encrypt data at rest and in transit. Use modern, industry-standard protocols (e.g., AES-256, TLS 1.3). Strip or mask Personally Identifiable Information (PII) whenever data is used for logging, analytics, or testing. Ensure the code architecture supports clear user opt-outs and data deletion requests (Right to be Forgotten). ### Core Implementation Checklist -- Check for Vulnerabilities: Scan for SQL injection, XSS, and CSRF before finalizing snippets. -- Audit Logs: Implement immutable logging for security-critical actions without logging sensitive PII. -- Dependency Hygiene: Use only verified, up-to-date libraries; avoid "ghost" dependencies with known CVEs. ## 14 Talk To Me Whenever one of the principles is difficult to implement (e.g. UX problems), one of the principles or a principle is violated, send me a message including - information about the module / function - the (possible) principle violation - why it happens - possible alternatives - your considerations on this case and why we might have to deviate ## 15 Educate Me As a vibe coder, I’m still relatively inexperienced when it comes to best practices in programming, but I’d love to learn more about them so I can be a better partner to you. So explain to me from time to time in an easy-to-understand way why you solved certain problems the way you did—especially regarding **software architecture**, **system consistency**, **security and privacy features**, and **coding conventions and best practices**.