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. 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:

  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.

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