Gå til innholdet
AI Boligassistent

implementation-strategy

Dette dokumentet er auto-synket fra kildefilene i boligassistent-repoet. Endringer her vil overskrives ved neste sync. Rediger kildefilen direkte.

Implementasjonsrekkefølge

Section titled “Implementasjonsrekkefølge”

Fase 0 — Prosjektoppsett (ikke en spec)

Section titled “Fase 0 — Prosjektoppsett (ikke en spec)”

Gjøres én gang, ikke spec-drevet. Fullført når pnpm typecheck, pnpm lint og pnpm test alle passerer, og Docker Compose starter uten feil.

0.1 — Repo og verktøy

Section titled “0.1 — Repo og verktøy”
  1. git init, første commit med all dokumentasjon
  2. GitHub-repo opprettet (privat), branch protection på main
  3. Turborepo + pnpm workspace-konfigurasjon (turbo.json, pnpm-workspace.yaml)
  4. .gitignore opprettes (se docs/architecture/git-strategy.md)
  5. .env.example opprettes med alle nøkler uten verdier

0.2 — Engineering setup

Section titled “0.2 — Engineering setup”
  1. Husky + lint-staged installert, pre-commit hook konfigurert
  2. commitlint installert, commit-msg hook konfigurert
  3. ESLint + Prettier konfigurert i monorepo
  4. GitHub Actions CI (ci.yml) opprettet — lint, typecheck, test
  5. PR-mal (.github/pull_request_template.md) opprettet

0.3 — Infrastruktur

Section titled “0.3 — Infrastruktur”
  1. Docker Compose (docker-compose.yml) med: PostgreSQL + pgvector, MinIO, API, Web
  2. docker-compose.test.yml for testmiljø
  3. MinIO-bucket opprettes ved oppstart
  4. Health check-endepunkt verifiserer database og MinIO

0.4 — Backend bootstrap

Section titled “0.4 — Backend bootstrap”
  1. Express.js app med middleware: Helmet, CORS, rate limiting, Pino-logging
  2. Global feilhåndterer med typede feilklasser (NotFoundError, ValidationError, ForbiddenError)
  3. Graceful shutdown (SIGTERM/SIGINT)
  4. /health-endepunkt

0.5 — Database

Section titled “0.5 — Database”
  1. Drizzle ORM konfigurert mot PostgreSQL
  2. pgvector-utvidelse aktivert
  3. Grunnleggende users- og houses-tabeller (migration 0001)
  4. pnpm db:migrate og pnpm db:generate scripts

0.6 — Auth

Section titled “0.6 — Auth”
  1. Auth.js v5 konfigurert med e-post/passord-provider
  2. Sesjon lagres i httpOnly-cookie
  3. Auth-middleware eksporteres for bruk i routes
  4. house_permissions-tabell — kobler bruker til hus

0.7 — Frontend bootstrap

Section titled “0.7 — Frontend bootstrap”
  1. React + Vite app med shadcn/ui og Tailwind CSS
  2. Innloggingsside
  3. Grunnleggende layout-shell (navigasjon, header)
  4. API-klient med automatisk 401-redirect til innlogging

Fase 1 — Kjernedata

Section titled “Fase 1 — Kjernedata”
  • Spec 001: Property og SpatialModel (rom, etasjer, uteområder)
  • Spec 002: BuildingSystems og Equipment

Fase 2 — Tilstand og planlegging

Section titled “Fase 2 — Tilstand og planlegging”
  • Spec 003: Issues, SafetyItems og Measurements
  • Spec 004: Observations
  • Spec 005: ImprovementIdeas og Tasks

Fase 3 — Design og interiør

Section titled “Fase 3 — Design og interiør”
  • Spec 006: DesignDirection og InteriorAssets
  • Bilder og dokumenter: KnowledgeLayer (Photo, Document, Manual)

Fase 4 — AI-assistent

Section titled “Fase 4 — AI-assistent”
  • Kontekstbygging og pgvector-søk
  • Chat-grensesnitt
  • Embedding-pipeline

Slik implementeres én spec

Section titled “Slik implementeres én spec”

For hver spec følges denne flyten:

1. Les spec-filen grundig
2. Identifiser alle entiteter og relasjoner som trengs
3. Skriv Drizzle-skjema
4. Generer og kjør migrasjon
5. Skriv service-funksjoner med tilhørende tester
6. Skriv API-routes med validering
7. Eksporter typer til packages/types
8. Bygg UI-komponenter
9. Kjør typecheck + lint + test
10. Kjør /review-spec for verifisering
11. Oppdater prosjektstatus

Bruk /implement-spec [spec-nummer] for å starte.

Kodekonvensjoner

Section titled “Kodekonvensjoner”

Lag-ansvar

Section titled “Lag-ansvar”
  • Routes: Validering av input, kall til service, returnere HTTP-respons. Ingen forretningslogikk.
  • Services: All forretningslogikk. Returnerer data eller kaster typede feil. Ingen HTTP-avhengighet.
  • DB-lag: Drizzle-queries. Kalles kun fra services.
  • AI-lag: Kontekstbygging, prompt-konstruksjon, kall til Claude/DALL-E.

Feilhåndtering

Section titled “Feilhåndtering”
// Service kaster typede feil
class NotFoundError extends Error { constructor(resource: string, id: string) { ... } }
class ValidationError extends Error { constructor(field: string, message: string) { ... } }


// Route håndterer feil
try {
  const room = await roomService.getRoom(id);
  res.json(room);
} catch (err) {
  if (err instanceof NotFoundError) res.status(404).json({ error: err.message });
  else res.status(500).json({ error: 'Internal error' });
}

TypeScript

Section titled “TypeScript”
  • Streng typechecking: strict: true i tsconfig
  • Alle API-request og response-typer defineres i packages/types
  • Ingen any — bruk unknown og type guards

Drizzle-skjema

Section titled “Drizzle-skjema”
  • Én skjemafil per domenelag: rooms.schema.ts, systems.schema.ts, osv.
  • Alle tabeller har id uuid DEFAULT gen_random_uuid(), created_at, created_by
  • Migrasjoner kjøres med drizzle-kit migrate

Testing

Section titled “Testing”

Testnivåer

Section titled “Testnivåer”
  1. Enhetstester — service-funksjoner med mocka database
  2. Integrasjonstester — API-routes mot testdatabase
  3. E2E-tester — ikke i MVP, men vurderes for kritiske brukerflyter

Testdekning

Section titled “Testdekning”

Minimum per spec:

  • Alle service-funksjoner testet
  • Alle API-endepunkter testet (happy path + error cases)
  • Akseptansekriteriene i spec-filen dekket av tester

Testverktøy

Section titled “Testverktøy”
  • Vitest (enhet + integrasjon)
  • Supertest (HTTP-testing av Express)
  • Test-database: PostgreSQL i Docker (samme konfigurasjon som prod)

Verifisering av spec

Section titled “Verifisering av spec”

Etter implementasjon, kjør /review-spec [spec-nummer] for å:

  1. Gå gjennom hvert akseptansekriterium
  2. Verifisere at domenereglene er overholdt
  3. Sjekke testdekning
  4. Opprette et evalueringsdokument i evaluations/

En spec er ikke ferdig implementert uten godkjent /review-spec.