CodeBuddy StarterKit

CodeBuddy StarterKit

The CodeBuddy StarterKit is a robust, production-ready project template specifically developed for use with RIDE. Its goal: to remove complexity and accelerate delivery of dependable, maintainable full-stack solutions. This kit features a carefully curated, opinionated technology stack and a battle-tested architecture designed to scale for both solo developers and professional teams.

---

What’s Included

• Strict IDesign Architecture: Clear separation of concerns for business logic, orchestration, persistence, and resource access.
• Frontend: React + TypeScript + MUI: Rapid, type-safe modern UI development with a production-tier component system.
• Backend: .NET 8 API (C#): Strongly typed business logic, workflow control, and extensibility.
• Supabase Integration: Lightning-fast database, authentication, and file storage.
• Cloud Optimized: Azure-ready deployment scripts and settings.
• Essentials Built-in: Authentication, user management, permissions, data access layers, and more.

---

StarterKit Technology Stack

• Backend: .NET 8 (C#)
  • Strong typing, decades of maturity, cloud integration, powerful compilers (Roslyn).
• Frontend: React + HTML/TypeScript/CSS
  • Most popular SPA framework, best-in-class developer experience, massive community and UI library support.
• Component Library: MUI
  • Consistency, accessibility, and rapid development with a widely adopted library.
• Cloud Hosting: Azure
  • Deep .NET integration, robust security, startup-ready pricing, AI model accessibility.
• Database & Auth: Supabase
  • PostgreSQL foundation, open source, instant database and user auth, no vendor lock-in, Document & Blob storage.

---

StarterKit Architecture: The IDesign Pattern

This architecture borrows some concepts from the IDesign Method (Juval Löwy), such as service-oriented decomposition. IDesign is all about sustainable, maintainable growth and change.

Key Components

• Views:

  • Top-level React components representing an entire screen or page (e.g., Dashboard, Login, Budget Overview).
  • Each view typically corresponds to a route in your application, handling all logic and layout for that “page.”
  • Each view imports and arranges smaller components as needed.
  • Views should focus on orchestration: data-fetching, passing state/props, and handling navigation—not fine-grained UI logic.

• Components:

  • Reusable UI building blocks composed to create views and other components (e.g., Buttons, Forms, Tables, Dialogs, User Avatars).
  • General Components: Common UI elements styled and configured for your app’s needs (buttons, cards, menus, etc).
  • Domain-Specific Components: Render or manage business-specific UI elements (e.g., BudgetRow, CategorySelector).
  • Prefer composition (nesting components) over repeated code.
  • Keep components as “dumb” as possible—take state and handlers as props.
  • Use MUI components and theming conventions wherever possible.

• Routing:

  • Route mapping connects URLs to views, using simple and protected route components to restrict access based on authentication or roles.
  • Define all routes centrally for visibility and maintainability.
  • Use wrapper components like ProtectedRoute for authorization checks.

• Stores:

  • State management containers, typically using Zustand, to hold transient UI state that spans multiple components (e.g., authenticated user, UI theme, draft form data).
  • Stores enable different components and views to react to shared state changes without prop-drilling.
  • Use stores for ephemeral, client-side state only; persist critical state to backend as needed.
  • Keep store logic isolated from UI components for testability and clarity.

• Front-End API Managers (.ts), Dtos, and Enums

  • The ONLY exit or access point for front-end business operations calling to the back-end.
  • Front-end Managers, Dtos, and Enums are Auto-Generated so neither you nor the AI has to create them
  • They will be created by looking at the back-end Managers, Dtos, and Enums and are auto-updated

• Managers (.cs)

  • The ONLY entry point for back-end business operations.
  • Orchestrate workflows and transactions.
  • Enforce business rules and direct calls to Engines or Accessors.
  • Stateful when needed to manage workflow context or transactions.

• Engines

  • Contain stateless, reusable business logic and computations.
  • Always deterministic and function-like: same input equals same output.
  • Never manage orchestration or workflow, only logic.

• Accessors

  • Interact directly with external resources (DBs, files, APIs).
  • Hide all connectivity, resource management, retries, and low-level errors.
  • Stateless, isolated adapters for swapping/extension.

• Utilities

  • General-purpose helpers for things like formatting, low-level math, etc.
  • Stateless and not tied to business problems.

---

Typical Call Chains and Rules

IDesign enforces a strict “downward only” dependency flow. Below is how a typical call moves through the system: UI (React) | Front End Managers | ↓ ServiceInvoker (Single API Endpoint) | ↓ Manager (e.g. BudgetManager) | | ↘ ↓ ↓ Engine Accessor | | Utility Resource (DB, API, etc)

Rules of Engagement (Back-End):

• Front-End Managers
  • May only call back-end Managers via the ServiceInvoker pattern.
• Back-End Managers
  • May call Engines, Accessors, or Utilities.
  • May NOT directly call other Managers.
    • Exception: Only via a queued call (deferred workflow), never direct. This maintains independence of business areas.
• Engines
  • May call Accessors or Utilities.
  • Must NOT call Managers or other Engines.
• Accessors
  • Must NOT call anything except Utilities.
• Utilities
  • Must not call anything outside their scope (pure helpers).

NO UPWARD or SIDEWAYS CALLS!
Each layer only goes “down”, never sideways (Managers-to-Managers) or “back up”.

---

Folder & Logic Structure

Folder	Purpose
/views/	Top-level React components representing an entire screen or page
/components/	Reusable UI building blocks composed to create views and other components
/stores/	State management containers, typically using Zustand, to hold transient UI state
/routes/	Route mapping connects URLs to views, using simple and protected route components
/api/	Front-end managers, Dtos, and enums (auto-generated)
/Contracts.Domain/	Core domain models: Database contracts (persisted data), Logic contracts, Enums
/Contracts.Dto/	Data Transfer Objects: Types used for API and inter-layer communication
/Managers/	Business orchestrators; each method = one backend operation
/Engines/	Stateless, reusable computational logic
/Accessors/	Resource interfaces; talk to databases, files, external APIs, etc.
/Utilities/	Stateless helpers (formatting, parsing, math, etc)

---

Workflow Example

Scenario: User adds a new budget category via the web UI.

1. UI: User fills a form and submits (“Add Budget Category”).
2. Store: Budget store tracks state if needed.
3. Front-End Manager: The BudgetManager.ts makes calls to back-end via ServiceInvoker.
4. ServiceInvoker: API receives a single DTO describing the action.
5. Back-End Manager: The BudgetManager.cs validates the request, and decides what workflow/actions are needed.
6. Engine: Called if business rules/calculations are needed (e.g., uniqueness, limit checks).
7. Accessor: Persists the new category to Supabase/MartenDB, or fetches additional info as needed.
8. Back-End Manager: Packages response in a DTO, returns to the front-end (through ServiceInvoker).
9. Front-End Manager: Receives the response DTO and returns the value to the store, view, or component.
10. UI: React updates state, user sees the new category immediately.

---

Updating & Customizing

• To update onboarding content: Replace this markdown file in /src/assets/ and redeploy. Changes appear instantly—no backend required!
• To add or change business logic: Add/extend Managers, Engines, or Accessors with new methods and contracts.
• To use different storage/resources: Swap or extend Accessors only—app logic and interface remain unchanged.

---

Further Reading

• IDesign Architecture by Juval Löwy
• .NET 8 Documentation
• ReactJS
• MUI Component Library
• Supabase
• Azure Documentation

---

Questions or suggestions?
Open a discussion on the repo or connect with the CodeBuddy community!