# InteriorScan — AGENTS.md

## Project Overview

InteriorScan is a SaaS platform for interior photogrammetry targeting real estate. Users upload photos of a property, the system reconstructs a 3D mesh, and visitors navigate the space in first-person (WASD + click-to-walk) — like a Doom map of a real apartment.

**Purpose**: Filter properties before physical visits. Save time for buyers and agents.

**Stack**: Next.js 16 App Router · Turborepo · Drizzle ORM · PostgreSQL · Valkey · three.js · COLMAP/OpenMVS · Stripe

**Repo**: https://git.d0a1.es/hermes/interiorscan

## Architecture

```
interiorscan/
├── apps/web/                    # Next.js 16 App Router (SSR + client)
│   ├── src/app/(marketing)/     # Landing, pricing, public pages
│   ├── src/app/(saas)/          # Auth-guarded dashboard
│   ├── src/app/api/             # Webhooks, health, processing callbacks
│   └── src/lib/3d/              # three.js viewer components (FPS controls, mesh loader)
├── apps/processor/              # Node.js worker — orchestrates COLMAP/OpenMVS pipeline
├── packages/
│   ├── auth/                    # better-auth + RBAC
│   ├── db/                      # Drizzle schema + migrations
│   ├── ui/                      # shadcn/ui v4 + Tailwind tokens
│   ├── utils/                   # Zod schemas, neverthrow, error catalog
│   └── ts-config/               # Shared TS configs
├── docker/                      # Docker Compose (web + postgres + valkey + GPU worker)
└── .specify/                    # Constitution, specs, plans
```

## Constitution

See `.specify/memory/constitution.md` — all development must comply.

## Key Decisions

- **FPS navigation**: WASD + click-to-walk (both modes). Not 360° panos.
- **Mobile-first capture**: iPhone/Android photos as baseline. LiDAR = enhancement.
- **Self-hosted**: All infra self-hosted except Stripe.
- **API-first**: Every feature has REST API before UI.
- **Open exports**: OBJ, E57, LAS/LAZ, DXF minimum. IFC in P4+.
- **Catastro SSOT**: Spanish Cadastro (INSPIRE WFS) is the single source of truth for building exterior geometry. Address → refcat → footprint polygon → exterior walls. Interior comes from photos.
- **3DGS for visuals**: Hybrid pipeline — mesh for collision/measurement, Gaussian Splatting for visual quality (gsplat MIT license, never graphdeco-inria research-only).
- **Plan inputs**: (1) Catastro address lookup, (2) DXF/SVG/PNG upload, (3) manual wall editor, in that order of preference.

## Development Commands

```bash
pnpm install          # Install dependencies
pnpm dev              # Start dev server (all apps)
pnpm build            # Production build
pnpm test             # Run Vitest
pnpm lint             # Biome check
pnpm typecheck        # TypeScript strict check
```

## Standards Reference

| Layer | Choice | Standard |
|---|---|---|
| Auth | better-auth | [SECURITY.md](https://git.d0a1.es/d0a1-agentic-crew/agentic-standards/src/branch/main/standards/SECURITY.md) |
| Design | d0a1 palettes | [DESIGN_SYSTEM.md](https://git.d0a1.es/d0a1-agentic-crew/agentic-standards/src/branch/main/standards/DESIGN_SYSTEM.md) |
| CSS | #app[data-theme] selectors | Design system token pattern |
| Lint | Biome 2.x only | [STANDARDS.md](https://git.d0a1.es/d0a1-agentic-crew/agentic-standards/src/branch/main/standards/STANDARDS.md) |
| Testing | Vitest v4 + Playwright | tpl-next-saas pattern |

## Branch Strategy

- `main` — production-ready
- `feat/###-description` — feature branches from spec IDs
- `fix/description` — bugfixes
- Conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`