Imported from dclawstack/dclaw-assets (AGENTS.md). Install upstream with npx skills add dclawstack/dclaw-assets. Copyright stays with the author.

DClaw App — Agent Development Guide

Read this file first before making any code changes. This document is the source of truth for architecture, anti-patterns, and development workflow.

App Identity

DClaw Assets is a vertical SaaS application built on the DClaw Stack.

• Backend Port: 8043 (FastAPI)
• Frontend Port: 3043 (Next.js)
• Database: dclaw_assets (PostgreSQL)
• Base API Path: /api/v1

Architecture Lock — DO NOT CHANGE

These are non-negotiable. If an agent suggests changing them, reject it.

Backend

• FastAPI with lifespan handler
• SQLAlchemy 2.0 — DeclarativeBase from app.models.base, NOT declarative_base(). Do NOT use MappedAsDataclass.
• Pydantic v2 schemas with ConfigDict(from_attributes=True)
• Async SQLAlchemy — create_async_engine + AsyncSession
• Repository pattern — all DB access through app/repositories/
• Dependency injection — Depends(get_db), never manual AsyncSession
• NO MOCK DATA — never use in-memory dicts
• pytest-asyncio==0.24.0 — pinned version, do not upgrade

Frontend

• Next.js 14+ App Router
• Tailwind CSS + custom UI components (pre-built in src/components/ui/)
• API client in src/lib/api.ts — typed fetch wrapper
• Environment variables — NEXT_PUBLIC_API_URL baked at build time. Dockerfile MUST declare ARG NEXT_PUBLIC_API_URL.
• DO NOT install shadcn CLI — use the pre-built components in src/components/ui/

Docker

• Backend: python:3.11-slim, non-root appuser, healthcheck with python urllib.request.urlopen()
• Frontend: node:20-alpine, port 3043
• Compose: container port MUST match EXPOSE/ENV PORT

Directory Structure

Assets/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   ├── main.py
│   │   │   ├── routes/health.py
│   │   │   └── v1/               # App-specific routers
│   │   ├── core/
│   │   │   ├── config.py
│   │   │   └── database.py       # Base(DeclarativeBase), engine, get_db
│   │   ├── models/
│   │   │   ├── base.py
│   │   │   └── ...               # App-specific models
│   │   ├── repositories/         # CRUD layer
│   │   ├── schemas/              # Pydantic v2
│   │   └── services/             # Business logic / AI
│   ├── alembic/
│   ├── tests/
│   │   ├── conftest.py           # Test DB override, client fixture
│   │   └── __init__.py           # REQUIRED for pytest discovery
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── app/                  # Next.js App Router
│   │   ├── components/ui/        # Pre-built UI components (see below)
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── input.tsx
│   │   │   ├── label.tsx
│   │   │   ├── badge.tsx
│   │   │   ├── select.tsx
│   │   │   ├── dialog.tsx
│   │   │   ├── table.tsx
│   │   │   ├── tabs.tsx
│   │   │   └── avatar.tsx
│   │   └── lib/
│   │       ├── api.ts
│   │       └── utils.ts          # cn() helper
│   └── Dockerfile
├── docker-compose.yml
├── .github/workflows/ci.yml      # DO NOT DELETE
├── helm/
└── .env.example

Pre-Built UI Components

The scaffold includes working UI components in frontend/src/components/ui/. Use these directly. Do NOT install shadcn CLI or @base-ui/react.

Required dependency: tailwindcss-animate must be in package.json dependencies (not devDependencies) because tailwind.config.ts imports it via plugins: [require("tailwindcss-animate")].

Available components:

• Button — variants: default, destructive, outline, secondary, ghost, link
• Card — Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
• Input — standard text input
• Label — form label
• Badge — variants: default, secondary, destructive, outline
• Select — native select with onValueChange support
• Dialog — modal with trigger, content, header, title
• Table — Table, TableHeader, TableBody, TableRow, TableHead, TableCell
• Tabs — Tabs, TabsList, TabsTrigger, TabsContent
• Avatar — Avatar, AvatarImage, AvatarFallback

Anti-Patterns — NEVER DO

Database Rules

1. All models MUST inherit from Base in app.models.base
2. All models MUST use Mapped[...] and mapped_column()
3. Never use default_factory= in mapped_column() — use default= instead
4. Relationships MUST specify lazy="selectin"
5. All new tables MUST get an alembic migration
6. Use ondelete="CASCADE" for child tables
7. Use ondelete="SET NULL" for optional references

How to Add a Feature

1. Read this file and PLAN-v1.2.md
2. Backend:
   • Add/update model in app/models/
   • Add/update schema in app/schemas/
   • Add repository in app/repositories/
   • Add/update router in app/api/v1/
   • Add tests in tests/
   • Generate alembic migration
3. Frontend:
   • Add API types/functions to src/lib/api.ts
   • Add page in src/app/ or component using pre-built UI components
4. Docker: Verify docker compose config and docker compose up -d
5. Commit with conventional commit message

Testing Requirements

• Every new repository MUST have tests
• Every new router endpoint MUST be covered
• Use pytest-asyncio with async test functions and @pytest.mark.asyncio
• Use httpx.AsyncClient with ASGITransport
• Override get_db dependency with test session in conftest.py
• Tests MUST use localhost:5432 for PostgreSQL (CI requirement)

Port Registry