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: VS Code Dev Container using private Docker image (ghcr.io/acedanger/finance-devcontainer:latest)

Development Environment

• Dev Container: The project uses a VS Code Dev Container for consistent development environments.
  • Container configuration in .devcontainer/devcontainer.json
  • Uses a private container image hosted on GitHub Container Registry
  • Image: ghcr.io/acedanger/finance-devcontainer:latest
  • Includes all necessary development tools and extensions
  • Configured with GitHub CLI and authentication
  • Features Docker-in-Docker support for additional container needs
• Container Features:
  • Node.js and npm pre-installed
  • Git and GitHub CLI configured
  • TypeScript support
  • VS Code extensions pre-configured
  • Docker-in-Docker capability
  • Automatic GitHub authentication
• Authentication:
  • Requires GitHub Personal Access Token for private container access
  • Token should be configured in .devcontainer/.env
  • GitHub CLI authentication handled in post-start command

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

• .devcontainer/: Development container configuration
  • devcontainer.json: VS Code Dev Container configuration
  • Dockerfile: Base container definition (for reference)
  • .env.example: Template for container environment variables
• 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. Fix Update Button Issue:

   • Fix the disabled state of the update button in transaction editing mode (see issue #33)
   • Ensure proper form validation state management
   • Test updates to transactions thoroughly

2. Implement Create Functionality:

   • Add client-side JavaScript to the AddTransactionForm.astro component (or enhance the script in index.astro) to handle form submission.
   • Prevent default form submission.
   • Perform basic client-side validation (required fields, numeric amount).
   • Send a POST request to the backend API with the new transaction data.
   • On success:
     • Clear the form.
     • Collapse the form (optional).
     • Refresh the transaction list for the current account (either by re-fetching or adding the new transaction to the client-side state).
     • Update the account balance display.
   • Handle API errors (display messages to the user).

3. Implement Update Functionality:

   • Add event listeners to the "Edit" buttons in TransactionTable.astro.
   • When "Edit" is clicked:
     • Expand the AddTransactionForm (or potentially use a modal).
     • Populate the form fields with the data from the selected transaction.
     • Change the form's submit button/logic to perform an update (PUT request to /api/transactions/:id).
   • On successful update:
     • Clear/reset the form.
     • Refresh the transaction list.
     • Update the account balance.
   • Handle API errors.

4. Implement Delete Functionality:

   • Add event listeners to the "Delete" buttons in TransactionTable.astro.
   • When "Delete" is clicked:
     • Show a confirmation dialog (e.g., window.confirm).
     • If confirmed, send a DELETE request to /api/transactions/:id.
   • On success:
     • Remove the transaction row from the UI.
     • Update the account balance.
   • Handle API errors.

5. Refine State Management: Continue improving the NanoStores implementation for better reactivity and handling of complex application states.

6. Error Handling: Implement more robust error handling and user feedback for API calls.

7. Styling/UI Improvements: Refine CSS, potentially add loading indicators, improve responsiveness further.

Code Style & Conventions

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.

// ❌ 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:

// 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/