architecture-api-separation.md

---

title: All Data Flows Through NestJS Backend impact: CRITICAL impactDescription: Single source of truth for business logic, security, and validation tags: architecture, api, nestjs, nextjs, separation

Паспорт документа

• Статус документа: living standard
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении инженерной практики, CI/CD, архитектурных правил или локального workflow
• Область применения: внутренние rule/reference-card документы для инженерной команды
• Связанные документы:
  • Индекс Agents
  • Команды разработки
  • Инженерные принципы

All Data Flows Through NestJS Backend

Impact: CRITICAL

The Next.js frontend never accesses the database directly. All data flows through the NestJS backend API. This ensures:

• Single place for business logic
• Consistent validation and authorization
• Proper error handling and logging
• Clean separation of concerns

Incorrect (Next.js accessing database directly):

// app/api/items/route.ts — DON'T do this!
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export async function GET() {
  const items = await prisma.item.findMany(); // Direct DB access from frontend!
  return Response.json(items);
}

Correct (Next.js calls NestJS API):

// apps/web/lib/api.ts — API client
const API_BASE = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:5001/api/v1';

export const api = {
  catalog: {
    async getItems(filters: CatalogFilters) {
      const params = new URLSearchParams(filters as Record<string, string>);
      const res = await fetch(`${API_BASE}/catalog?${params}`, { next: { revalidate: 300 } });
      if (!res.ok) throw new Error('Failed to fetch items');
      return res.json();
    },
  },
};

// apps/web/app/page.tsx — Server Component fetches from NestJS
export default async function CatalogPage({ searchParams }) {
  const items = await api.catalog.getItems(searchParams);
  return <CourseFeed items={items} />;
}

Exception: Next.js API routes (app/api/*) are acceptable ONLY for:

• Authentication callbacks (OAuth, JWT refresh)
• Webhook receivers that need to be on the frontend domain
• BFF (Backend-for-Frontend) pattern where you aggregate multiple NestJS calls

In all other cases, the frontend calls the NestJS backend directly.