Copilot instructions

1---
2applyTo: '**'
3---
4 
5# Copilot instructions (English — concise)
6 
7Purpose: provide short, actionable guidance so Copilot suggestions match project conventions.
8 
9## Common Development Commands
10 
11### Development Server
12- `bin/dev` - Start development server (Rails, Sidekiq, Tailwind CSS watcher)
13- `bin/rails server` - Start Rails server only
14- `bin/rails console` - Open Rails console
15 
16### Testing
17- `bin/rails test` - Run all tests
18- `bin/rails test:db` - Run tests with database reset
19- `DISABLE_PARALLELIZATION=true bin/rails test:system` - Run system tests only (use sparingly - they take longer)
20- `bin/rails test test/models/account_test.rb` - Run specific test file
21- `bin/rails test test/models/account_test.rb:42` - Run specific test at line
22 
23### Linting & Formatting
24- `bin/rubocop` - Run Ruby linter
25- `npm run lint` - Check JavaScript/TypeScript code
26- `npm run lint:fix` - Fix JavaScript/TypeScript issues
27- `npm run format` - Format JavaScript/TypeScript code
28- `bin/brakeman` - Run security analysis
29 
30### Database
31- `bin/rails db:prepare` - Create and migrate database
32- `bin/rails db:migrate` - Run pending migrations
33- `bin/rails db:rollback` - Rollback last migration
34- `bin/rails db:seed` - Load seed data
35 
36### Setup
37- `bin/setup` - Initial project setup (installs dependencies, prepares database)
38 
39## Pre-PR workflow (run locally before opening PR)
40- Tests: bin/rails test (all), DISABLE_PARALLELIZATION=true bin/rails test:system (when applicable)
41- Linters: bin/rubocop -f github -a; bundle exec erb_lint ./app/**/*.erb -a
42- Security: bin/brakeman --no-pager
43 
44## High-Level Architecture
45 
46### Application Modes
47The app runs in two modes:
48- **Managed** (Rails.application.config.app_mode = "managed")
49- **Self-hosted** (Rails.application.config.app_mode = "self_hosted")
50 
51### Core Domain Model
52The application is built around financial data management with these key relationships:
53- **User** → has many **Accounts** → has many **Transactions**
54- **Account** types: checking, savings, credit cards, investments, crypto, loans, properties
55- **Transaction** → belongs to **Category**, can have **Tags** and **Rules**
56- **Investment accounts** → have **Holdings** → track **Securities** via **Trades**
57 
58### API Architecture
59The application provides both internal and external APIs:
60- Internal API: Controllers serve JSON via Turbo for SPA-like interactions
61- External API: `/api/v1/` namespace with Doorkeeper OAuth and API key authentication
62- API responses use Jbuilder templates for JSON rendering.
63- Rate limiting via Rack::Attack with configurable limits per API key
64 
65### Sync & Import System
66Two primary data ingestion methods:
671. **Plaid Integration**: Real-time bank account syncing
68   - `PlaidItem` manages connections
69   - `Sync` tracks sync operations
70   - Background jobs handle data updates
712. **CSV Import**: Manual data import with mapping
72   - `Import` manages import sessions
73   - Supports transaction and balance imports
74   - Custom field mapping with transformation rules
75 
76### Background Processing
77Sidekiq handles asynchronous tasks:
78- Account syncing (`SyncJob`)
79- Import processing (`ImportJob`)
80- AI chat responses (`AssistantResponseJob`)
81- Scheduled maintenance via sidekiq-cron
82 
83### Frontend Architecture
84- **Hotwire Stack**: Turbo + Stimulus for reactive UI without heavy JavaScript
85- **ViewComponents**: Reusable UI components in `app/components/`
86- **Stimulus Controllers**: Handle interactivity, organized alongside components
87- **Charts**: D3.js for financial visualizations (time series, donut, sankey)
88- **Styling**: Tailwind CSS v4.x with custom design system
89  - Design system defined in `app/assets/tailwind/sure-design-system.css`
90  - Always use functional tokens (e.g., `text-primary` not `text-white`)
91  - Prefer semantic HTML elements over JS components
92  - Use `icon` helper for icons, never `lucide_icon` directly
93 
94### Multi-Currency Support
95- All monetary values stored in base currency (user's primary currency)
96- `Money` objects handle currency conversion and formatting
97- Historical exchange rates for accurate reporting
98 
99### Security & Authentication
100- Session-based auth for web users
101- API authentication via:
102  - OAuth2 (Doorkeeper) for third-party apps
103  - API keys with JWT tokens for direct API access
104- Scoped permissions system for API access
105- Strong parameters and CSRF protection throughout
106 
107## Key rules
108- Project modes: "managed" or "self_hosted".
109- Domain: User → Accounts → Transactions. Keep business logic in models, controllers thin.
110 
111Authentication & context
112- Use Current.user and Current.family (never current_user / current_family).
113 
114Testing conventions
115- Use Minitest + fixtures (no RSpec, no FactoryBot).
116- Use mocha for mocks where needed; VCR for external API tests.
117 
118Frontend conventions
119- Hotwire-first: Turbo + Stimulus.
120- Prefer semantic HTML, Turbo Frames, server-side formatting.
121- Use the helper icon for icons (do not use lucide_icon directly).
122- Use Tailwind design tokens (text-primary, bg-container, etc.).
123 
124Backend & architecture
125- Skinny controllers, fat models.
126- Prefer built-in Rails patterns; add dependencies only with strong justification.
127- Sidekiq for background jobs (e.g., SyncJob, ImportJob, AssistantResponseJob).
128 
129API & security
130- External API under /api/v1 with Doorkeeper / API keys; respect CSRF and strong params.
131- Follow rate limits and auth strategies already in project.
132 
133Stimulus & components
134- Keep controllers small (< 7 targets); pass data via data-*-value.
135- Prefer ViewComponents for reusable or complex UI.
136 
137## Component Architecture
138 
139### ViewComponent vs Partials Decision Making
140 
141**Use ViewComponents when:**
142- Element has complex logic or styling patterns
143- Element will be reused across multiple views/contexts
144- Element needs structured styling with variants/sizes
145- Element requires interactive behavior or Stimulus controllers
146- Element has configurable slots or complex APIs
147- Element needs accessibility features or ARIA support
148 
149**Use Partials when:**
150- Element is primarily static HTML with minimal logic
151- Element is used in only one or few specific contexts
152- Element is simple template content
153- Element doesn't need variants, sizes, or complex configuration
154- Element is more about content organization than reusable functionality
155 
156**Component Guidelines:**
157- Prefer components over partials when available
158- Keep domain logic OUT of view templates
159- Logic belongs in component files, not template files
160 
161### Stimulus Controller Guidelines
162 
163**Declarative Actions (Required):**
164```erb
165<!-- GOOD: Declarative - HTML declares what happens -->
166<div data-controller="toggle">
167  <button data-action="click->toggle#toggle" data-toggle-target="button">Show</button>
168  <div data-toggle-target="content" class="hidden">Hello World!</div>
169</div>
170```
171 
172**Controller Best Practices:**
173- Keep controllers lightweight and simple (< 7 targets)
174- Use private methods and expose clear public API
175- Single responsibility or highly related responsibilities
176- Component controllers stay in component directory, global controllers in `app/javascript/controllers/`
177- Pass data via `data-*-value` attributes, not inline JavaScript
178 
179## Testing Philosophy
180 
181### General Testing Rules
182- **ALWAYS use Minitest + fixtures + Mocha** (NEVER RSpec or FactoryBot)
183- Keep fixtures minimal (2-3 per model for base cases)
184- Create edge cases on-the-fly within test context
185- Use Rails helpers for large fixture creation needs
186 
187### Test Quality Guidelines
188- **Write minimal, effective tests** - system tests sparingly
189- **Only test critical and important code paths**
190- **Test boundaries correctly:**
191  - Commands: test they were called with correct params
192  - Queries: test output
193  - Don't test implementation details of other classes
194 
195### Testing Examples
196 
197```ruby
198# GOOD - Testing critical domain business logic
199test "syncs balances" do
200  Holding::Syncer.any_instance.expects(:sync_holdings).returns([]).once
201  assert_difference "@account.balances.count", 2 do
202    Balance::Syncer.new(@account, strategy: :forward).sync_balances
203  end
204end
205 
206# BAD - Testing ActiveRecord functionality
207test "saves balance" do 
208  balance_record = Balance.new(balance: 100, currency: "USD")
209  assert balance_record.save
210end
211```
212 
213### Stubs and Mocks
214- Use `mocha` gem
215- Prefer `OpenStruct` for mock instances
216- Only mock what's necessary
217 
218## Performance Considerations
219- Database queries optimized with proper indexes
220- N+1 queries prevented via includes/joins
221- Background jobs for heavy operations
222- Caching strategies for expensive calculations
223- Turbo Frames for partial page updates
224 
225## Development Workflow
226- Feature branches merged to `main`
227- Docker support for consistent environments
228- Environment variables via `.env` files
229- Lookbook for component development (`/design-system`)
230- Letter Opener for email preview in development
231 
232## Project Conventions
233 
234### Convention 1: Minimize Dependencies
235- Push Rails to its limits before adding new dependencies
236- Strong technical/business reason required for new dependencies
237- Favor old and reliable over new and flashy
238 
239### Convention 2: Skinny Controllers, Fat Models
240- Business logic in `app/models/` folder, avoid `app/services/`
241- Use Rails concerns and POROs for organization
242- Models should answer questions about themselves: `account.balance_series` not `AccountSeries.new(account).call`
243 
244### Convention 3: Hotwire-First Frontend
245- **Native HTML preferred over JS components**
246  - Use `<dialog>` for modals, `<details><summary>` for disclosures
247  - **Leverage Turbo frames** for page sections over client-side solutions
248  - **Query params for state** over localStorage/sessions
249  - **Server-side formatting** for currencies, numbers, dates
250  - **Always use `icon` helper** in `application_helper.rb`, NEVER `lucide_icon` directly
251 
252### Convention 4: Optimize for Simplicity
253- Prioritize good OOP domain design over performance
254- Focus performance only on critical/global areas (avoid N+1 queries, mindful of global layouts)
255 
256### Convention 5: Database vs ActiveRecord Validations
257- Simple validations (null checks, unique indexes) in DB
258- ActiveRecord validations for convenience in forms (prefer client-side when possible)
259- Complex validations and business logic in ActiveRecord
260 
261## TailwindCSS Design System
262 
263### Design System Rules
264- **Always reference `app/assets/tailwind/sure-design-system.css`** for primitives and tokens
265- **Use functional tokens** defined in design system:
266  - `text-primary` instead of `text-white`
267  - `bg-container` instead of `bg-white`
268  - `border border-secondary` instead of `border border-gray-200`
269- **NEVER create new styles** in design system files without permission
270- **Always generate semantic HTML**
271 
272Disallowed suggestions / behaviors
273- Do NOT propose running system commands in PRs (rails server, rails credentials, touching tmp files, auto-running migrations).
274- Avoid adding new global styles to design system without permission.
275- Do not produce offensive, dangerous, or non-technical content.
276 
277Style for suggestions
278- Make changes atomic and testable; explain impact briefly.
279- Keep suggestions concise and aligned with existing code.
280- Respect existing tests; add tests when changing critical logic.
281 
282Notes from repository config
283- If .gemini/config.yaml disables automated code_review, still provide clear summaries and fix suggestions in PRs.
284