Design First Approach

📝 1. Feature Description

The first step is to clearly and concisely define the feature. This involves outlining its business purpose, its ultimate goal, and any potential challenges or risks associated with its implementation. A solid feature description sets the stage for all subsequent design and development work.

⚙️ 2. Non-Functional Requirements

This section defines the technical quality attributes of the system that are not covered by business requirements. These requirements ensure the system operates effectively. You only need to specify the ones relevant to the feature; the default assumption is that existing NFRs are not negatively impacted.

• Performance: How fast must the system respond?
• Security: What are the security constraints and requirements?
• Scalability: How should the system handle growth in users or data?
• Maintainability: How easy should it be to update or fix the system?
• Reliability: How often can the system fail? What is the expected uptime?
• Usability: How easy should the system be for the target users?

➡️ 3. Sequence Diagram

A sequence diagram visually represents the interactions between different components or systems over time. It's an excellent tool for detailing the step-by-step logic of a process, such as an API call or a user interaction flow. Use Mermaid syntax to create as many diagrams as needed to describe all relevant flows.

Example using Mermaid syntax:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

✨ 4. Actions

This section provides a detailed, technical breakdown of the work required. List all the specific code units (classes, modules, functions, etc.) that need to be created or modified. The description should be clear enough for any developer to understand and implement the feature.

For example:

• Create `MagicLinks::InvoicesController` - for payment links
• Create `MagicLinks::Organizations::UsersController` - for organization users
• Update URLs
• In `MagicLinks::PaymentsController`:
  • Create page which generates payment link for the invoice
  • Initiate Flywire script
  • Flywire modal needs to be rendered

🏗️ 5. C4 Diagrams

If the feature involves architectural changes, use the C4 model to describe them. The C4 model helps visualize software architecture at different levels of detail (Context, Containers, Components, Code). Only create diagrams for the levels that are relevant to the feature. If there are no architectural changes, this section can be skipped.

🗄️ 6. Database Structure

Detail any changes to the database schema. This includes new tables or columns, modifications to existing ones, or removals. Using a text-based format like the one provided by dbdiagram.io is recommended for clarity and version control.

🔗 7. API Documentation

Document all changes to the application's API endpoints. Clearly specify any new endpoints, changes to existing ones (like a new method or URL), and any endpoints that will be removed.

✅ 8. Test Coverage Requirements

Define the testing requirements for the feature to ensure its quality and stability. By default, any new feature should not decrease the existing test coverage and must include comprehensive tests for all new API endpoints.

• Do NOT reduce overall test coverage.
• 100% of new API endpoints must be covered by tests.