> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avyratech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Standards

> Enterprise-grade API development standards for Tonnex.

# API Standards

To ensure consistency, security, and AI-native readiness, all API development in Tonnex must follow these standards.

## Architecture

We use **NestJS** as the core logic engine, **Drizzle ORM** for database access, and **Supabase** for Auth and RLS.

### Service Pattern

All services must use the `db.rls` pattern to ensure multi-tenancy is enforced.

```typescript theme={null}
@Injectable()
export class MyService {
  async performAction(token: string, data: any) {
    const db = createDrizzleSupabaseClient(token);
    return await db.rls(async (tx) => {
      // Logic goes here
    });
  }
}
```

## Agentic Tier API Design

To be truly AI-Native, APIs must act as intelligent interfaces for autonomous agents, facilitating reasoning and self-correction.

1. **Semantic Reasoning**: Services should return enriched data including a `reasoning` field explaining *why* an action was taken (e.g., "Vehicle chosen via proximity algorithm").
2. **Actionable Feedback (Self-Correction Hints)**: Error responses should include a `correctionHint`. Instead of just `400 Bad Request`, provide context like `"Invalid pincode for the given city. Please correct or provide a valid pincode for [City Name]."`
3. **Static Discovery (The Agent Manual)**: Use deep Swagger (`@ApiOperation`) instructions as a manual for AI agents to plan their actions *before* execution.
4. **Standardized Response Envelope**:
   * **Success**: `{ success: true, data: T, reasoning?: string }`
   * **Error**: `{ success: false, error: string, correctionHint?: string }`

```typescript theme={null}
// Standard Agentic Service Pattern
@Injectable()
export class MyService {
  async performAction(token: string, userId: string, data: any) {
    const db = createDrizzleSupabaseClient(token);
    return await db.rls(async (tx) => {
      // 1. Perform Business Logic
      // 2. Return data + reasoning
      return {
        data: { id: "123" },
        reasoning: "Action performed because of condition X."
      };
    });
  }
}
```