Agent Portal Development Guidelines

You are an AI coding assistant working on Agent Portal, an enterprise agentic AI platform for building, deploying, monitoring, and governing AI agents.

Core Philosophy

**Plan → Code → Test → Complete**

Never mark a task complete without testing

Always research before implementing

Ask before making breaking changes

Protect sensitive data at all costs

Critical Rules

1. Test Before Complete (MANDATORY)

Code alone is NOT complete. You MUST test before marking any TODO as done.

**Testing Procedure:**

1. **Backend API**: Test with `curl http://localhost:8000/api/...`

2. **Frontend/UI**: Use browser MCP tools to test in actual browser

3. **Integration**: Test full user flow end-to-end

**Browser Testing (REQUIRED for UI Changes):**

Use `browser_navigate` to open changed pages

Use `browser_snapshot` to verify page loaded correctly

Use `browser_click`, `browser_type` to simulate user interactions

Use `browser_console_messages` to check for errors

Use `browser_take_screenshot` for visual verification

Test responsive design if applicable

**Completion Flow:**

```

1. Write/modify code

2. Restart service if needed

3. Execute actual test (curl for backend, browser tools for frontend)

4. Verify result

5. ✅ No errors → Mark complete

6. ❌ Errors → Fix and retry from step 2

```

2. Sensitive Data Protection (CRITICAL)

**NEVER:**

Create `.env` backup files (`.env.bak`, `.env.backup`)

Add sensitive files to git

Expose API keys in logs

Hardcode credentials

Run `git clean -fdx` without protecting `.env`

**Safe Practices:**

Use `.env.example` with placeholders

Reference via `os.environ.get('API_KEY')`

Verify `.gitignore` includes sensitive files

3. Reuse Before Creating

**Pre-Code Checklist (MANDATORY):**

Before writing ANY new function/component:

1. Search codebase for similar functionality (`grep` for keywords)

2. Check if existing code can be used, extended, or wrapped

3. If creating new, document why existing code can't be reused

**Reuse Criteria:**

80%+ similar → Use existing, modify if needed

50-80% similar → Extend existing or extract common logic

<50% similar → Create new, document rationale

**Prohibited:**

```

❌ Creating fetchData2() when fetchData() exists

❌ Duplicate modal components

❌ Copy-paste with minor modifications

```

**Correct:**

```

✅ Import and use existing utilities

✅ Extend functions with optional parameters

✅ Create shared components, import everywhere

```

Required Reference Documents

**Priority 1 — Domain Rules (`.cursor/rules/*.mdc`):**

`agent-development.mdc` — Agent development with GenAI monitoring

`backend-api.mdc` — FastAPI patterns, services, error handling

`ui-development.mdc` — SvelteKit, Tailwind, UI patterns

`admin-screens.mdc` — Admin UI, Glassmorphism design

`monitoring-development.mdc` — ClickHouse, OTEL traces, GenAI standards

`datacloud-development.mdc` — Database connectors, Text-to-SQL

`mcp-gateway.mdc` — MCP servers, Kong integration

**Priority 2 — Project Docs:**

`CLAUDE.md` — Quick reference

`AGENTS.md` — Project structure, workflows

**Priority 3 — Skills (On-Demand):**

`webui/.skills/ui-summary.json` — Route/pattern lookup

Query Skills files with `jq` for detailed information

Service Management

Service Dependency Order (CRITICAL)

**Always restart services in this order:**

```

Layer 1: Infrastructure (mariadb, redis)

↓ wait 10s

Layer 2: Core Services (litellm, kong, kong-db)

↓ wait 10s

Layer 3: Observability (otel-collector, clickhouse, prometheus, langfuse)

↓ wait 10s

Layer 4: Application (backend, chromadb, minio)

↓ wait 5s

Layer 5: Frontend (webui)

```

Safe Restart Procedure

**Before restart:**

```bash

Check current status

./scripts/health-check.sh

Check state file

cat .cursor/state/services.json | jq '.services'

```

**Single service restart:**

```bash

Create rollback point

./scripts/pre-build.sh backend

Restart service

docker compose restart backend

Verify

./scripts/health-check.sh

```

**Service rebuild:**

```bash

Pre-build check (creates rollback point)

./scripts/pre-build.sh backend

Build (--no-cache for clean rebuild)

docker compose build --no-cache backend

Start

docker compose up -d backend

Verify

./scripts/health-check.sh

```

**On failure:**

```bash

Rollback to previous state

./scripts/rollback.sh latest

```

Key Services

|---------|------|------|--------------|

| mariadb | 3306 | App Database | - |

| redis | 6379 | Cache | - |

Development Workflows

UI Development Checklist

**Before starting:**

[ ] Check route path in `ui-summary.json`

[ ] Review existing patterns in target file

[ ] Confirm dark/light mode support needed

**During development:**

[ ] Use Glassmorphism pattern for Admin pages

[ ] Support dark/light mode

[ ] Test responsive design

[ ] Use `/api/*` proxy for API calls (not direct URLs)

**After completion:**

[ ] Browser test on multiple viewports using browser MCP tools

[ ] Check console errors with `browser_console_messages`

[ ] Test dark/light mode toggle

[ ] Verify no CORS errors (use Vite proxy)

Backend API Development Checklist

**Before starting:**

[ ] Check existing service patterns in `backend/app/services/`

[ ] Review similar endpoints

[ ] Plan error handling

**During development:**

[ ] Use `async def`

[ ] Add type hints

[ ] Set timeout for external calls (default 30s)

[ ] Handle errors with `HTTPException`

**After completion:**

[ ] Test with `curl`

[ ] Check OpenAPI docs at `/docs`

[ ] Test error cases (401, 403, 404, 500)

Database Operations

**MariaDB:**

```bash

Check schema

docker compose exec mariadb mariadb -uroot -prootpass agent_portal \

-e "DESCRIBE table_name;"

Modify schema

docker compose exec mariadb mariadb -uroot -prootpass agent_portal \

-e "ALTER TABLE table_name ADD column_name VARCHAR(255);"

```

**ClickHouse (Monitoring):**

```bash

Check schema

docker compose exec monitoring-clickhouse clickhouse-client \

--query "DESCRIBE otel_2.otel_traces"

Query traces (IMPORTANT: Use ResourceAttributes map)

✅ CORRECT

WHERE ResourceAttributes['project_id'] = 'value'

❌ WRONG (project_id is not a direct column)

WHERE project_id = 'value'

```

Troubleshooting

Port Conflicts

```bash

Check port usage

lsof -i :8000

lsof -i :3001

Kill process

kill -9 <PID>

```

Container Issues

```bash

Check status

docker compose ps

Check logs

docker compose logs <service> --tail=100

Force recreate

docker compose up -d --force-recreate <service>

Full rebuild

docker compose build --no-cache <service>

docker compose up -d <service>

```

CORS Errors

```javascript

// ❌ WRONG: Direct call

fetch('http://localhost:8000/api/...')

// ✅ CORRECT: Use Vite proxy

fetch('/api/...')

```

Check `webui/vite.config.ts` for proxy configuration.

Router Not Registered

```python

Check backend/app/main.py

app.include_router(example_router, prefix="/example")

Verify in container

docker compose exec backend cat /app/app/main.py | grep include_router

Rebuild if needed

docker compose build --no-cache backend

docker compose up -d backend

```

Code Patterns

Backend (FastAPI)

```python

✅ Good pattern

from fastapi import APIRouter, HTTPException, Depends

from typing import Optional

import asyncio

router = APIRouter()

@router.get("/endpoint")

async def get_data(

param: str,

timeout: int = 30

) -> dict:

try:

result = await asyncio.wait_for(

fetch_data(param),

timeout=timeout

)

return result

except asyncio.TimeoutError:

raise HTTPException(status_code=504, detail="Request timeout")

except Exception as e:

raise HTTPException(status_code=500, detail=str(e))

```

Frontend (SvelteKit)

```svelte

import { onMount } from 'svelte';

let data: DataType | null = null;

let loading = false;

let error: string | null = null;

onMount(async () => {

try {

loading = true;

// ✅ Use proxy path

const response = await fetch('/api/endpoint');

if (!response.ok) throw new Error('Failed to fetch');

data = await response.json();

} catch (e) {

error = e.message;

} finally {

loading = false;

}

});

</script>

{#if loading}

<p>Loading...</p>

{:else if error}

<p class="text-red-500">{error}</p>

{:else if data}

{/if}

</div>

```

Decision Framework

When to Ask vs Proceed

**Ask user when:**

Task is ambiguous or has multiple valid interpretations

Change affects existing working functionality

Operation involves sensitive data

Significant architectural decision needed

Breaking change to public API

**Proceed autonomously when:**

Task is clearly defined

Following established patterns

Adding new isolated feature

Fixing obvious bugs

Routine refactoring within single file

When to Refactor vs Patch

**Patch (default for bug fixes):**

Minimal change to fix issue

No surrounding code cleanup

Keep PR small and focused

**Refactor (only when requested):**

User explicitly asks for cleanup

Bug fix impossible without refactoring

Technical debt blocking feature development

Learning System

After completing significant tasks:

Record learnings in `.cursor/learnings/`

Update documentation if patterns change

Note what worked well and what didn't

Summary

1. **Test before complete** — Use curl for backend, browser MCP tools for frontend

2. **Protect sensitive data** — Never expose credentials

3. **Reuse before creating** — Search codebase thoroughly first

4. **Follow service order** — Respect dependency chain when restarting

5. **Reference domain rules** — Check `.cursor/rules/*.mdc` before implementing

6. **Use browser tools** — Mandatory testing for all UI changes

7. **Handle errors properly** — Timeouts, HTTPException, try-catch

8. **Ask when uncertain** — Better to clarify than break functionality

Remember: **Plan → Code → Test → Complete**. Never skip the testing step.

Agent Portal Development Guidelines

Safety Concern

Agent Portal Development Guidelines

Core Philosophy

Critical Rules

1. Test Before Complete (MANDATORY)

2. Sensitive Data Protection (CRITICAL)

3. Reuse Before Creating

Required Reference Documents

Service Management

Service Dependency Order (CRITICAL)

Safe Restart Procedure

Check current status

Check state file

Create rollback point

Restart service

Verify

Pre-build check (creates rollback point)

Build (--no-cache for clean rebuild)

Start

Verify

Rollback to previous state

Key Services

Development Workflows

UI Development Checklist

Backend API Development Checklist

Database Operations

Check schema

Modify schema

Check schema

Query traces (IMPORTANT: Use ResourceAttributes map)

✅ CORRECT

❌ WRONG (project_id is not a direct column)

Troubleshooting

Port Conflicts

Check port usage

Kill process

Container Issues

Check status

Check logs

Force recreate

Full rebuild

CORS Errors

Router Not Registered

Check backend/app/main.py

Verify in container

Rebuild if needed

Code Patterns

Backend (FastAPI)

✅ Good pattern

Frontend (SvelteKit)

Decision Framework

When to Ask vs Proceed

When to Refactor vs Patch

Learning System

Summary

Reviews (0)