Software Architecture

1---
2name: software-architecture
3description: Guide for quality focused software architecture. This skill should be used when users want to write code, design architecture, analyze code, in any case that relates to software development.
4---
5 
6# Software Architecture Development Skill
7 
8This skill provides guidance for quality focused software development and architecture. It is based on Clean Architecture and Domain Driven Design principles.
9 
10## Code Style Rules
11 
12### General Principles
13 
14- **Early return pattern**: Always use early returns when possible, over nested conditions for better readability
15- Avoid code duplication through creation of reusable functions and modules
16- Decompose long (more than 80 lines of code) components and functions into multiple smaller components and functions. If they cannot be used anywhere else, keep it in the same file. But if file longer than 200 lines of code, it should be split into multiple files.
17- Use arrow functions instead of function declarations when possible
18 
19### Best Practices
20 
21#### Library-First Approach
22 
23- **ALWAYS search for existing solutions before writing custom code**
24  - Check npm for existing libraries that solve the problem
25  - Evaluate existing services/SaaS solutions
26  - Consider third-party APIs for common functionality
27- Use libraries instead of writing your own utils or helpers. For example, use `cockatiel` instead of writing your own retry logic.
28- **When custom code IS justified:**
29  - Specific business logic unique to the domain
30  - Performance-critical paths with special requirements
31  - When external dependencies would be overkill
32  - Security-sensitive code requiring full control
33  - When existing solutions don't meet requirements after thorough evaluation
34 
35#### Architecture and Design
36 
37- **Clean Architecture & DDD Principles:**
38  - Follow domain-driven design and ubiquitous language
39  - Separate domain entities from infrastructure concerns
40  - Keep business logic independent of frameworks
41  - Define use cases clearly and keep them isolated
42- **Naming Conventions:**
43  - **AVOID** generic names: `utils`, `helpers`, `common`, `shared`
44  - **USE** domain-specific names: `OrderCalculator`, `UserAuthenticator`, `InvoiceGenerator`
45  - Follow bounded context naming patterns
46  - Each module should have a single, clear purpose
47- **Separation of Concerns:**
48  - Do NOT mix business logic with UI components
49  - Keep database queries out of controllers
50  - Maintain clear boundaries between contexts
51  - Ensure proper separation of responsibilities
52 
53#### Anti-Patterns to Avoid
54 
55- **NIH (Not Invented Here) Syndrome:**
56  - Don't build custom auth when Auth0/Supabase exists
57  - Don't write custom state management instead of using Redux/Zustand
58  - Don't create custom form validation instead of using established libraries
59- **Poor Architectural Choices:**
60  - Mixing business logic with UI components
61  - Database queries directly in controllers
62  - Lack of clear separation of concerns
63- **Generic Naming Anti-Patterns:**
64  - `utils.js` with 50 unrelated functions
65  - `helpers/misc.js` as a dumping ground
66  - `common/shared.js` with unclear purpose
67- Remember: Every line of custom code is a liability that needs maintenance, testing, and documentation
68 
69#### Code Quality
70 
71- Proper error handling with typed catch blocks
72- Break down complex logic into smaller, reusable functions
73- Avoid deep nesting (max 3 levels)
74- Keep functions focused and under 50 lines when possible
75- Keep files focused and under 200 lines of code when possible
76