Financial Transaction Service (Project Sentinel)

📊 Project Overview

Project Sentinel is an asynchronous web service responsible for managing user accounts, processing real-time financial transactions, and providing live query updates to client dashboards [1, 6]. It is designed to ensure transactional integrity and high availability.

Core Architecture

This service follows a modern data flow based on local-first synchronization patterns [6]:

Database (Postgres): Primary data store, utilizing logical replication [7, 8].
Sync Engine (Electric): Handles the read-path synchronization from Postgres to clients via HTTP [6].
Client DB (TanStack DB): Embedded client database used for live queries and transactional optimistic mutations [6].

This separation ensures that mutations are instant (optimistic write on the client) and later reconciled via the Electric stream, dropping the optimistic state when the final change arrives from the backend [9].

💻 Human Development Setup

These instructions are for setting up the environment locally for a human contributor [5].

Prerequisites

Node.js (for pnpm)
Docker Compose (for local Postgres setup)
Python 3.11+ (for FastAPI backend components)

Getting Started

Clone the Repository: git clone my-finance-app
Install Dependencies:
- Install server dependencies: pnpm install [10, 11].
- Install Python backend dependencies (see requirements.txt): pip install -r requirements.txt [12].
Database Setup (using Docker Compose): Run the standard stack defined in docker-compose.yaml to spin up Postgres and the Electric backend [7]: docker compose up -d Run migrations: pnpm migrate [11]
Start the Dev Server:
- Start the client application: pnpm dev [10, 11].
- Start the FastAPI/Python backend: uvicorn app.main:app --reload [12].

🧪 Testing and Validation

All code changes must pass the full test suite before merging.

Run all tests: pnpm test [10].
Run specific package tests (Monorepo setup): pnpm turbo run test --filter <project_name> [13].
Code Formatting: We enforce PEP8 standards (for Python) and use the Black formatter [12].

🤝 Contribution Guidelines

We use conventional commits. Please follow these guidelines:

PR Title Format: [<component_name>] <Short description of change> [13, 14].
Pre-Commit Check: Always run pnpm lint and pnpm test before committing [13, 14].
Testing: Add or update tests for any new or modified code [13].

Raw

AGENTS.md

AGENTS.md – Project Sentinel (Operational Context)

Audience: Coding agents/codegen tools [6] Goal: Ensure all generated code adheres to security rules, stylistic patterns, and uses Model Context Protocol (MCP) servers for dependency validation and complex task decomposition [2, 17].

🛠 Setup and Environment Commands

The agent should use the following commands for automated execution and validation:

Install Dependencies: pnpm install [10]
Run Tests (Non-interactive execution): pnpm test --silent --ci (Modified test commands for non-interactive execution are necessary for agents) [2, 18].
Run Linter: pnpm lint --fix (Fix linting issues automatically) [13].

🔒 Security Rules (ALWAYS ENFORCE)

Instructions regarding security considerations that minimize attack surface [11, 19]:

Secrets: Never expose SOURCE_SECRET or any environment variables containing sensitive tokens to the browser or in generated client-side code [11]. Inject them server-side via proxy [11].
API Access: The Electric HTTP API is public by default; enforce authorization at the server/proxy layer [11]. Never call Electric directly from production client code [11].
Input Sanitization: Sanitize all user input before processing or database interaction [12].
Configuration Minimization: Keep this AGENTS.md file minimal to reduce the "Rules File Backdoor" attack surface [19].

✨ Code Style Guidelines

Apply these stylistic conventions to all new or modified code [10, 12, 20]:

Language: TypeScript strict mode [10].
Quotes/Semicolons: Use single quotes, and avoid semicolons where possible [10].
Patterns: Prefer functional patterns for data transformation [10].
Formatting: Use the Black formatter for Python code (black .) [12].

📡 Agent-Specific Tools and MCP Configuration

The following tools are available via Model Context Protocol (MCP) servers and should be used for complex tasks [2, 17]:

Sequential Thinking: Use this tool when planning or thinking on complex tasks involving multiple steps (e.g., integrating client-side optimistic mutations with server-side API writes) [21-23].
Context7: Consult this tool for correct Python or NPM package names and version-specific API documentation [17, 22]. This is critical for avoiding package hallucinations (slopsquatting) [22, 24].
Tavily Search: Use for real-time web lookups, specifically for verifying library existence or finding recent design patterns (verify-first approach) [22, 23].

🔄 Write-Path Contract (Mandatory Data Flow)

When implementing new API endpoints, adhere strictly to the write-path contract to manage optimistic state [9]:

UI mutates client collection (instant optimistic update) [9].
Collection calls the dedicated API endpoint in onInsert/onUpdate/onDelete [9].
API writes to Postgres and must return the Postgres transaction ID (txid) [9].
Client awaits the txid on the Electric stream, which triggers reconciliation and drops the optimistic state [9].
- Postgres requirement: The backend must retrieve the transaction ID using SELECT pg_current_xact_id()::xid::text as txid and return it as an integer [9].

⚠️ Critical Agent Gotchas

Package Verification: Require inline existence checks (pip index versions <pkg>) before finalizing dependency lists in generated code [25].
Dependency Naming: Be aware that cross-ecosystem name borrowing is common. Verify package names are specifically present in PyPI, not just in general documentation (e.g., a JavaScript library with a similar name) [26].
Testing: If a testing command is listed here, the agent will attempt to execute the relevant programmatic checks and fix failures before completing the task [18].