Project Workflows

Project Workflows

Official project procedures. See 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 search_path = public, extensions. Use explicit eshop.tablename for eshop schema tables — never rely on search_path to resolve them.
2. Permissions: ALWAYS check permissions (e.g. check_is_admin...).
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: mcp_supabase-mcp-server_list_projects to get the project_id.
2. Read: view_file the local SQL file.
3. Execute: mcp_supabase-mcp-server_execute_sql with the project_id and query (file content).

2.6 Deno Edge Function Deployment via MCP

To deploy/update Edge Functions:

1. Upload: mcp_supabase-mcp-server_deploy_edge_function.
   • files: Read content of index.ts, deno.json etc. first.
2. Note: Always list_dir and view_file 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).
2. Cleanup: Remove analysis.txt, test_results.txt, temp_*.sql.
3. Verify:
   • Run ./automation/test_all.sh (Web + DB + Integration).
   • Run fvm flutter analyze.
4. Sync Translations:
   • node web_client/scripts/unify_translations.js (Flutter <-> Web)
   • node web_client/scripts/reorder_cs_like_en.js (CS Structure)
5. 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.
6. 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 web_client/src/app_config.js.
• Database: DATABASE_URL required for test runner.

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

Source: vkh-cr/festapp — distributed by TomeVault.