Project Workflows

**Official project procedures. See
[CONTRIBUTING.md](../../../../../CONTRIBUTING.md) for full details.**

0. Context & Architecture (CRITICAL)

Before starting complex tasks, read: docs/architecture/ai_context.md

It explains:

• Split Brain Logic (SQL vs Dart).
• Directory Structure (Where features live).
• Key Patterns (Permissions, Navigation).

1. Security Workflow (RPCs)

When writing PostgreSQL functions (database/functions/):

1. Search Path: All functions live in public schema. Always set searchpath = public, extensions. Use explicit eshop.tablename for eshop schema tables — never rely on searchpath to resolve them.
2. Permissions: ALWAYS check permissions (e.g. checkisadmin...).
3. References: Do not assume RLS protects SECURITY DEFINER functions.

2. Testing Workflow

Run All Tests (Recommended)

Runs both Web Client and Database tests.

./automation/test_all.sh

Run Database Tests Only

Use when modifying SQL functions or migrations.

# All DB tests
node web_client/scripts/run_db_tests.js

# Specific file
node web_client/scripts/run_db_tests.js database/tests/path/to/test.sql

Run Integration Tests

System-level tests (requires Supabase connection).

node tests/integration/bank_import.js --existing-token "..."

2.5 Database Deployment via MCP

To deploy/update SQL functions remotely:

1. Identify: mcpsupabase-mcp-serverlist_projects to get the

project_id.

1. Read: view_file the local SQL file.
2. Execute: mcpsupabase-mcp-serverexecutesql with the projectid and

query (file content).

2.6 Deno Edge Function Deployment via MCP

To deploy/update Edge Functions:

1. Upload: mcpsupabase-mcp-serverdeployedgefunction.

- files: Read content of index.ts, deno.json etc. first.

1. Note: Always listdir and viewfile to get the latest content.

3. Flutter Workflow

Code Generation (Build Runner)

Run this after modifying Models, Routes, or Services (Refit):

fvm dart run build_runner build --delete-conflicting-outputs

4. Commit Workflow

Before committing, run this checklist:

1. Configuration Check: ./automation/apply_config.sh (Ensures

version/theme sync).

1. Cleanup: Remove analysis.txt, testresults.txt, temp*.sql.
2. Verify:

- Run ./automation/test_all.sh (Web + DB + Integration). - Run fvm flutter analyze.

1. Sync Translations:

- node webclient/scripts/unifytranslations.js (Flutter <-> Web) - node webclient/scripts/reordercslikeen.js (CS Structure)

1. Security Check:

- Scan for Secrets: Ensure no API keys, tokens, or passwords are in the staged files. - Check .env: Confirm .env files are ignored and not being committed.

1. Stage Only (NEVER COMMIT):

- git add . - STOP. Do not run git commit. The user will perform the commit.

5. Codebase Cleanup Workflow

Run this checklist when performing a codebase-wide cleanup (e.g. comments, logs).

Checklist Structure

Ensure you sweep these areas:

1. Documentation & Config: .gitignore, README.md, project.conf.
2. Database: Functions, Tables, Tests, Migrations.
3. Flutter: Components, Services, Models.
4. Web Client: Components, Scripts, Tests.
5. Automation: Scripts (TS/JS).

What to Look For

• Conversational Comments: Remove "I think", "maybe", "check this", "TODO".
• Redundant Comments: Remove comments that blindly state the code (e.g.

// returns true above return true;).

• Debugging Artifacts: Remove console.log, print(), commented-out code

blocks.

Systematic Audit Strategy

For complex cross-cutting concerns (leaks, API changes):

1. Identify: Run a search (e.g., grep) to find all candidate files.
2. List: Create a comprehensive checklist in your task.md artifact.
3. Iterate: Go through the list one by one. Do not skip.
4. Verify: Check off items only after verification.

6. Secret Management

• Local: Keys in .env.local (NOT committed).
• Web Client: Public keys in webclient/src/appconfig.js.
• Database: DATABASE_URL required for test runner.

Rule: Never commit changes automatically. Always leave them staged for the
user.