finance/.github/copilot-instructions.md

# GitHub Copilot Instructions for Finance App

## Project Overview

This project is a financial transaction management application built with Astro and TypeScript, using Prisma for database operations. It follows a two-column dashboard layout for managing bank accounts and transactions.

## Technology Stack

*   **Framework:** Astro (latest version)
*   **Language:** TypeScript, JavaScript (client-side scripts), HTML, CSS
*   **Styling:** Plain CSS (`src/styles/global.css`)
*   **Data:** Using Astro's built-in API routes in `src/pages/api/` with persistent database storage via Prisma ORM (`src/data/db.service.ts`).
*   **Development Environment:** Local development with Node.js, PostgreSQL, and standard tooling

## Development Environment

*   **Local Development:** The project uses standard Node.js development practices.
    *   Node.js (version 18 or higher)
    *   PostgreSQL for database storage
    *   Prisma ORM for database operations
    *   TypeScript for type safety
    *   Biome.js for code formatting and linting
    *   Husky for Git hooks and code quality enforcement

## Current State & Key Features

*   **Layout:** A two-column dashboard layout (`src/layouts/BaseLayout.astro`, `src/pages/index.astro`) is implemented.
    *   **Sidebar:** (`src/components/Sidebar.astro`) Contains account selection dropdown and a collapsible section for adding new transactions. Includes an account summary section.
    *   **Main Content:** (`src/components/MainContent.astro`) Displays the header with the current account name and the transaction list.
*   **Components:** Separate Astro components exist for major UI sections (Sidebar, MainContent, TransactionTable, AddTransactionForm, AccountSummary).
*   **API Integration:** 
    *   API routes structure implemented in `src/pages/api/`
    *   Database integration using Prisma ORM in `src/data/db.service.ts`
    *   All API endpoints implemented and fully functional:
        *   GET /api/accounts - List all accounts
        *   GET /api/accounts/:id - Get single account details
        *   GET /api/accounts/:id/transactions - Get transactions for an account
        *   POST /api/transactions - Create new transaction
        *   PUT /api/transactions/:id - Update existing transaction
        *   DELETE /api/transactions/:id - Delete transaction
    *   Comprehensive error handling and validation
    *   Database persistence with proper transaction support
*   **Account Switching:** Selecting an account from the dropdown in the sidebar correctly updates the Main Content area (header, transaction table) and the Account Summary section using client-side JavaScript (`<script>` tag in `index.astro`).
*   **Collapsible Form:** The "Add Transaction" section in the sidebar (`src/components/AddTransactionForm.astro`) can be expanded and collapsed using client-side JavaScript (`<script>` tag in `AddTransactionForm.astro`).
*   **Basic Formatting:** Utility functions (`src/utils.ts`) exist for formatting currency and dates, used both server-side and client-side (mirrored in `index.astro` script).
*   **Types:** Basic TypeScript types for `Account` and `Transaction` are defined in `src/types.ts`.
*   **State Management:** Client-side state management using NanoStores, providing a reactive state for transactions and account data (`src/stores/transactionStore.ts`).
*   **Database Integration:** Complete integration with a relational database using Prisma ORM, including transaction support to maintain data integrity.

## File Structure Overview

*   `src/components/`: Reusable UI components.
*   `src/data/`: Data store and persistence layer.
    *   `db.service.ts`: Database service layer using Prisma ORM
    *   `prisma.ts`: Prisma client initialization
*   `src/layouts/`: Base page layout(s).
*   `src/pages/`: Astro pages and API routes.
    *   `index.astro`: Main page
    *   `api/`: Backend API endpoints
        *   `accounts/`: Account-related endpoints
        *   `transactions/`: Transaction-related endpoints
*   `src/stores/`: Client-side state management.
    *   `transactionStore.ts`: NanoStore implementation for transactions
*   `src/styles/`: Global CSS styles.
*   `src/types.ts`: TypeScript type definitions.
*   `src/utils.ts`: Utility functions (formatting, etc.).
*   `public/`: Static assets.
*   `prisma/`: Database schema and migrations.
    *   `schema.prisma`: Prisma schema definition
    *   `migrations/`: Database migrations
    *   `seed.ts`: Seed data script

## Next Steps & TODOs

1. **Implement Frontend Transaction Management:**
   * Add client-side JavaScript to the `AddTransactionForm.astro` component to handle form submission
   * Implement proper form validation for transaction data
   * Connect the form to the API endpoints using fetch requests
   * Handle success/error responses from the API
   * Update UI state after successful operations

2. **Complete UI Interaction for CRUD Operations:**
   * Add event listeners to "Edit" buttons in `TransactionTable.astro`
   * Implement edit mode in the transaction form
   * Add confirmation dialog for transaction deletion
   * Ensure account balances update correctly after transactions change
   * Implement proper error messaging for failed operations

3. **Enhance Error Handling:**
   * Add user-friendly error messages for API errors
   * Implement form validation with visual feedback
   * Add loading states during API operations
   * Handle network errors gracefully

4. **Improve State Management:**
   * Refine the NanoStores implementation for better reactivity
   * Add proper state synchronization between components
   * Implement optimistic UI updates for better perceived performance
   * Consider implementing proper state machines for complex UI states

5. **Add User Authentication & Authorization:**
   * Implement user login/registration functionality
   * Add authentication middleware to API endpoints
   * Restrict access to accounts based on user ownership
   * Implement session management

6. **Enhance Testing Coverage:**
   * Add more unit tests for UI components
   * Expand integration tests for API endpoints
   * Add end-to-end tests for critical user flows
   * Implement automated testing in CI pipeline

7. **UI/UX Improvements:**
   * Add loading indicators for async operations
   * Improve mobile responsiveness
   * Add dark mode support
   * Enhance accessibility features

## Code Style & Conventions

### Shell Scripts

All shell scripts should follow these conventions:

- Use `#!/usr/bin/env bash` instead of direct path to bash
- Include standard safety flags at the start of each script:
  ```bash
  set -o errexit  # Exit on error
  set -o errtrace # Exit on error inside functions
  set -o nounset  # Error on undefined variables
  set -o pipefail # Error if any command in a pipe fails
  ```
- Use `readonly` for constants and configuration values
- Write error messages to stderr using `>&2`
- Use proper error handling and exit codes
- Validate all required parameters and dependencies
- Use `[[` instead of `[` for better feature support
- Quote all variable expansions
- Use `${variable:-}` pattern for safe variable expansion
- Handle special characters in input properly
- Include clear error messages and validation
- Group configuration/constants at the top of the script
- Add descriptive comments for complex logic
- Follow consistent indentation and formatting

### Import Path Aliases

Always use the path aliases defined in `tsconfig.json` instead of relative imports. This makes the code more maintainable and easier to refactor.

```typescript
// ❌ DON'T use relative imports like this
import { transactionService } from '../../../../data/db.service';
import type { Transaction } from '../../../../types';

// ✅ DO use path aliases like this
import { transactionService } from '@data/db.service';
import type { Transaction } from '@types';
```

The following path aliases are configured:

- `@/*`: Maps to `src/*` for any source files
- `@components/*`: Maps to `src/components/*` for component imports
- `@layouts/*`: Maps to `src/layouts/*` for layout imports
- `@data/*`: Maps to `src/data/*` for data services and database operations
- `@pages/*`: Maps to `src/pages/*` for page components
- `@styles/*`: Maps to `src/styles/*` for style imports
- `@stores/*`: Maps to `src/stores/*` for state management
- `@utils/*`: Maps to `src/utils.ts` for utility functions
- `@types`: Maps to `src/types.ts` for type imports

### TypeScript Usage

- Use TypeScript for all new files
- Use proper type annotations and avoid `any` types
- For imports that are only used as types, use `import type`:

```typescript
// For values (like services, components)
import { accountService } from '@data/db.service';

// For types only
import type { Account, Transaction } from '@types';
```

### Prisma & Database Operations

- Always handle Prisma's `Decimal` types appropriately:
  - Convert to `number` using `Number()` when sending to the client
  - Use the `number | Decimal` union type in interfaces

### Component Structure

- Keep components focused on specific tasks
- Use Astro components for server-rendered content
- Use React components (`.tsx`) for interactive UI elements

### API Endpoints

- Follow RESTful conventions
- Include proper error handling
- Validate input data thoroughly
- Return appropriate HTTP status codes

## Styling

- Use CSS variables for consistent theming
- Follow the established color scheme and design patterns
- Ensure responsive design works on various screen sizes

## File Structure

Keep new files organized according to the established project structure:
- Components in `src/components/`
- API endpoints in `src/pages/api/`
- Services in `src/data/`
- State management in `src/stores/`
- Styles in `src/styles/`