Cursor rule

1---
2description: 
3globs: 
4alwaysApply: true
5---
6This rule serves as high-level documentation for how you should write code in this codebase. 
7 
8## Project Tech Stack
9 
10- Web framework: Ruby on Rails
11  - Minitest + fixtures for testing
12  - Propshaft for asset pipeline
13  - Hotwire Turbo/Stimulus for SPA-like UI/UX
14  - TailwindCSS for styles
15  - Lucide Icons for icons
16  - OpenAI for AI chat
17- Database: PostgreSQL
18- Jobs: Sidekiq + Redis
19- External
20  - Payments: Stripe
21  - User bank data syncing: Plaid
22 
23## Project conventions
24 
25These conventions should be used when writing code for the project.
26 
27### Convention 1: Minimize dependencies, vanilla Rails is plenty
28 
29Dependencies are a natural part of building software, but we aim to minimize them when possible to keep this open-source codebase easy to understand, maintain, and contribute to.
30 
31- Push Rails to its limits before adding new dependencies
32- When a new dependency is added, there must be a strong technical or business reason to add it
33- When adding dependencies, you should favor old and reliable over new and flashy 
34 
35### Convention 2: Leverage POROs and concerns over "service objects"
36 
37This codebase adopts a "skinny controller, fat models" convention.  Furthermore, we put almost _everything_ directly in the `app/models/` folder and avoid separate folders for business logic such as `app/services/`.
38 
39- Organize large pieces of business logic into Rails concerns and POROs (Plain ole' Ruby Objects)
40- While a Rails concern _may_ offer shared functionality (i.e. "duck types"), it can also be a "one-off" concern that is only included in one place for better organization and readability.
41- When concerns are used for code organization, they should be organized around the "traits" of a model; not for simply moving code to another spot in the codebase.
42- When possible, models should answer questions about themselves—for example, we might have a method, `account.balance_series` that returns a time-series of the account's most recent balances.  We prefer this over something more service-like such as `AccountSeries.new(account).call`.
43 
44### Convention 3: Leverage Hotwire, write semantic HTML, CSS, and JS, prefer server-side solutions
45 
46- Native HTML is always preferred over JS-based components
47  - Example 1: Use `<dialog>` element for modals instead of creating a custom component
48  - Example 2: Use `<details><summary>...</summary></details>` for disclosures rather than custom components
49- Leverage Turbo frames to break up the page over JS-driven client-side solutions
50  - Example 1: A good example of turbo frame usage is in [application.html.erb](mdc:app/views/layouts/application.html.erb) where we load [chats_controller.rb](mdc:app/controllers/chats_controller.rb) actions in a turbo frame in the global layout
51- Leverage query params in the URL for state over local storage and sessions.  If absolutely necessary, utilize the DB for persistent state.
52- Use Turbo streams to enhance functionality, but do not solely depend on it
53- Format currencies, numbers, dates, and other values server-side, then pass to Stimulus controllers for display only
54- Keep client-side code for where it truly shines.  For example, @bulk_select_controller.js is a case where server-side solutions would degrade the user experience significantly.  When bulk-selecting entries, client-side solutions are the way to go and Stimulus provides the right toolset to achieve this.
55- Always use the `icon` helper in [application_helper.rb](mdc:app/helpers/application_helper.rb) for icons.  NEVER use `lucide_icon` helper directly.
56 
57The Hotwire suite (Turbo/Stimulus) works very well with these native elements and we optimize for this.
58 
59### Convention 4: Optimize for simplicitly and clarity
60 
61All code should maximize readability and simplicity.
62 
63- Prioritize good OOP domain design over performance
64- Only focus on performance for critical and global areas of the codebase; otherwise, don't sweat the small stuff.
65  - Example 1: be mindful of loading large data payloads in global layouts
66  - Example 2: Avoid N+1 queries
67 
68### Convention 5: Use ActiveRecord for complex validations, DB for simple ones, keep business logic out of DB
69 
70- Enforce `null` checks, unique indexes, and other simple validations in the DB
71- ActiveRecord validations _may_ mirror the DB level ones, but not 100% necessary.  These are for convenience when error handling in forms.  Always prefer client-side form validation when possible.
72- Complex validations and business logic should remain in ActiveRecord
73 
74