Financial Transaction Manager

A web application for managing financial transactions across multiple bank accounts.

Project Overview

• Purpose: Provides a user interface for CRUD operations on financial transactions.
• Technology: Built with Astro, TypeScript, and plain CSS, utilizing Astro API routes.
• Layout: Features a two-column dashboard design with a sidebar for account selection/actions and a main area for transaction display.
• Data Management: Uses Prisma ORM for database operations (src/data/db.service.ts), accessed via API endpoints (src/pages/api/).
• Key Features (Implemented & Planned): Account switching, transaction listing, adding, editing, and deleting transactions.

Logs

This app is currently deployed using Cloudflare Pages. The logs can be viewed with the npx wrangler pages deployment tail --project-name finance command.

Development Environment Setup

For detailed setup instructions, including container building, environment configuration, and troubleshooting, see ENVIRONMENT_SETUP.md.

GitHub MCP Server

The project uses GitHub's MCP server for development tasks. The server runs in a Docker container and is automatically configured when you open the project in a devcontainer.

Configuration

• The MCP server uses GitHub authentication via Personal Access Token
• Token is stored securely in .devcontainer/.env (not committed to repository)
• GitHub CLI is installed in the devcontainer for easier authentication management
• Container health monitoring is configured

Usage

The MCP server will automatically start when you open the project in a devcontainer. If you need to manually authenticate:

1. Run gh auth login in the terminal
2. Follow the prompts to authenticate with your GitHub account

Database Setup

The project uses Prisma ORM for database operations. To set up the database:

1. Create a .env file in the project root with your database connection string:

   DATABASE_URL="postgresql://username:password@localhost:5432/finance"
   

2. Run database migrations:

   npx prisma migrate dev
   

3. Seed the database with initial data (optional):

   npx prisma db seed
   

4. To view and manage your data visually:

   npx prisma studio
   

Path Aliases

This project uses TypeScript path aliases for cleaner imports. Instead of using relative paths like ../../../../data/db.service, use the following aliases:

• @/* - Maps to src/*
• @components/* - Maps to src/components/*
• @layouts/* - Maps to src/layouts/*
• @data/* - Maps to src/data/*
• @pages/* - Maps to src/pages/*
• @styles/* - Maps to src/styles/*
• @stores/* - Maps to src/stores/*
• @utils/* - Maps to src/utils.ts
• @types - Maps to src/types.ts

Example:

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

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

Development Container Setup

GitHub Personal Access Token

Before using the development container, you'll need a GitHub Personal Access Token (PAT) with the following permissions:

• repo (Full control of private repositories)
• read:packages (Download container images)
• write:packages (Upload container images)
• delete:packages (Optional: manage container versions)
• workflow (GitHub Actions integration)

Using the Development Container

Command Line Interface

You can build and start the development container using the devcontainer CLI:

# Build the container
devcontainer build .

# Start the container (with post-create command)
devcontainer up --workspace-folder .

# Start the container (skip post-create)
devcontainer up --workspace-folder . --skip-post-create

VS Code

1. Open the project in VS Code
2. Press F1 and run "Dev Containers: Rebuild and Reopen in Container"
   • To skip post-create steps: Press F1 and run "Dev Containers: Rebuild Container Without Cache"

Troubleshooting

• If GitHub authentication fails, ensure your PAT is correctly set in .devcontainer/.env
• For network issues, try rebuilding the container with --no-cache option
• Check the VS Code "Dev Containers" output panel for detailed logs