# Architecture

Lobby technical architecture, tech stack, infrastructure decisions

# Tech Stack

# Tech Stack — Lobby

## Statusoversikt

| Lag | Teknologi | Status |
|-----|-----------|--------|
| Frontend | Next.js 15 + React 19 + TypeScript + Tailwind + shadcn/ui | Vedtatt |
| Backend | TBD — Node.js/TypeScript ELLER Java/Spring Boot | **ADR needed** |
| Database | PostgreSQL + RLS (multi-tenancy) | Vedtatt |
| AI | Claude API (Anthropic) | Vedtatt |
| Mobile | React Native + Expo | Phase 2 |
| Infra | TBD — Vercel+Supabase vs Azure | **ADR needed** |
| Monorepo | Turborepo | Vedtatt (følger Bilko-mønster) |

---

## Frontend

**Stack:** Next.js 15 + React 19 + TypeScript + Tailwind CSS + shadcn/ui

| Valg | Begrunnelse |
|------|-------------|
| Next.js 15 | SSR, App Router, server components — samme som Bilko (delte lærdommer) |
| React 19 | Server Actions, concurrent features — reduserer boilerplate |
| TypeScript | Type safety, bedre DX, færre runtime-feil |
| Tailwind CSS | Utility-first, rask prototyping, konsistent design |
| shadcn/ui | Tilgjengelig, kopierbar komponent-bibliotek, ikke locked-in |

---

## Backend (ADR Pending)

**Status: Beslutning kreves av CEO/arkitekt**

### Alternativ A — Node.js + TypeScript (Hono/Express)

| Fordel | Ulempe |
|--------|--------|
| Samme språk som frontend (TypeScript) | Svakere type-system vs Java |
| Raskere onboarding for JS-devs | Event loop — ikke egnet for CPU-heavy tasks |
| Lettere deployment (Vercel/Railway) | Mindre modent for enterprise-patterns |
| Bilko-erfaring kan gjenbrukes | |

### Alternativ B — Java + Spring Boot

| Fordel | Ulempe |
|--------|--------|
| Sterke typer, robust for enterprise | Annet språk enn frontend |
| Godt testet for compliance-systemer | Tyngre oppstart og deployment |
| Utmerket støtte for multi-tenancy patterns | Krever Java-kompetanse |
| LumisCare bruker Java — erfaring finnes | |

**Anbefaling:** Node.js/TypeScript for Phase 1 (fart og konsistens). Java vurderes for Phase 3+ (kompleksitet øker).

---

## Database

**Stack:** PostgreSQL + Row Level Security (RLS)

### Multi-tenancy via RLS

```sql
-- Hvert selskap er en "tenant"
-- RLS sikrer at firma A aldri kan se firma Bs data
ALTER TABLE employees ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON employees
  USING (company_id = current_setting('app.current_company_id')::uuid);
```

### Kjernedatamodell

```
Company (org_number, name, address, industry)
├── Employee (personal_info, employment_info, role)
│   ├── Document (type, file, expiry_date)
│   ├── Absence (type, start, end, status, approver)
│   └── OnboardingTask (step, status, due_date)
├── Department (name, parent, manager)
├── HMSHandbook (version, content, generated_at)
└── ComplianceCheck (regulation, status, last_checked)
```

**ORM:** Prisma (type-safe, god migrering, støtter PostgreSQL RLS)

---

## AI

**Stack:** Claude API (Anthropic)

| Modell | Brukstilfelle |
|--------|--------------|
| Claude Haiku | Rutineoppgaver — kategorisering, varsler, enkle svar |
| Claude Sonnet | Kompleks generering — HMS-håndbøker, onboarding-flyter, analyser |

### AI-brukstilfeller Phase 1

1. **HMS-håndbok-generator** — Company info → 40–80 siders compliant håndbok
2. **Onboarding-flyt-generator** — Stillingsbeskrivelse → komplett plan
3. **Arbeidslogg-transkripsjon** — Talenotat → strukturert logg
4. **HR-analyser** — Fraværsdata → innsikt og varsler
5. **Compliance-status** — Regelendringer → påvirkning for kunden

---

## Mobile (Phase 2)

**Stack:** React Native + Expo

- Deler UI-komponenter med web via shared packages
- Native check-in (GPS, kamera for dokumenter)
- Offline-støtte for feltarbeidere
- Push-varsler for vaktplaner og fravær

---

## Infrastruktur (ADR Pending)

### Alternativ A — Vercel + Supabase

| Fordel | Ulempe |
|--------|--------|
| Rask oppstart, minimal ops | US-hosting (GDPR-kompleksitet) |
| Bilko og andre ALAI-produkter bruker dette | Supabase RLS-quirks |
| Vercel AI SDK integrerer godt med Claude | Kostnad skalerer raskt |

### Alternativ B — Azure (Norway East)

| Fordel | Ulempe |
|--------|--------|
| Norsk datacenter — sterk GDPR-posisjon | Høyere ops-overhead |
| Compliance selling point | Tregere oppstart |
| Azure AD → BankID-integrasjon | Dyrere for tidlig fase |

**Anbefaling:** Vercel+Supabase for Phase 1 (fart), migrer til Azure Norway East etter 50+ kunder (compliance selling point).

---

## DNA fra LumisCare

**Referanse:** `~/projects/client/lumiscare/` — enterprise helseplattform vi bygde.

Lobby deler DNA med LumisCare:

| Domene | LumisCare | Lobby |
|--------|-----------|-------|
| Besøk | Hjemmebesøk (hjemmesykepleie) | Kundebesøk (feltarbeid) |
| Planlegging | Vaktplanlegging (sykepleiere) | Skiftplanlegging |
| HR | Ansatthåndtering | HR-modul |
| Multi-tenancy | Per kommune | Per bedrift |
| Compliance | Norske helseregler | Arbeidsmiljøloven |

**Gjenbruk:** Autentiseringsmønstre, multi-tenancy RLS-arkitektur, besøks-domenmodell, planleggingslogikk.
**Unngå:** LumisCares over-engineering for enterprise — Lobby starter lettere.

---

## Ikke-funksjonelle krav

| Krav | Mål |
|------|-----|
| Responstid | <500ms for alle sider |
| Oppetid | 99.5%+ |
| GDPR | DPA, sletting, eksport fra dag 1 |
| Språk | Norsk bokmål primær, nynorsk Phase 2 |
| Mobil | Responsiv web Phase 1, native app Phase 2 |
| Sikkerhet | OWASP top 10, SOC 2 (Phase 3+) |

# Key ADRs Needed

# Key ADRs Needed — Lobby

## Hva er en ADR?

En **Architecture Decision Record (ADR)** dokumenterer en viktig arkitekturavgjørelse: kontekst, alternativer vurdert, beslutning tatt og konsekvenser. Gir fremtidige utviklere forståelse for *hvorfor*, ikke bare *hva*.

Format: `~/ALAI/products/Lobby/docs/architecture/adr-NNN-tittel.md`

---

## Ventende ADRs — Krever CEO/Arkitekt-beslutning

### ADR-001 — Backend Framework

**Status:** OPEN — blokkerer Phase 1 byggestart

**Spørsmål:** Node.js/TypeScript (Hono/Express) ELLER Java/Spring Boot?

| Kriterium | Node.js/TS | Java/Spring Boot |
|-----------|-----------|-----------------|
| Utviklingshastighet | Raskere (samme språk) | Tregere oppstart |
| Type safety | God (TS) | Utmerket (Java) |
| Skalerbarhet | God nok for Phase 1-3 | Bedre for Phase 4+ |
| ALAI-erfaring | Høy (Bilko, Drop, etc.) | Medium (LumisCare) |
| Compliance-egnethet | Akseptabel | Sterk |
| Deployment-enkelthet | Enkel (Vercel/Railway) | Middels (Docker/Azure) |

**Anbefalt beslutningsdato:** Før Phase 1 kickoff
**Beslutningstaker:** Alem (CEO) + John (Arkitekt)

---

### ADR-002 — Infrastruktur og Hosting

**Status:** OPEN — påvirker GDPR-posisjonering og kostnad

**Spørsmål:** Vercel + Supabase ELLER Azure Norway East?

| Kriterium | Vercel + Supabase | Azure Norway East |
|-----------|------------------|------------------|
| Time to market | Dager | Uker |
| GDPR-posisjonering | Akseptabel (US-hosting, SCCs) | Sterk (norsk datacenter) |
| Ops-overhead | Minimal | Medium |
| Kostnad Phase 1 | Lav (~500 NOK/mnd) | Medium (~2K NOK/mnd) |
| Skalering | God | Utmerket |
| ALAI-erfaring | Høy | Lav |

**Kompromiss-alternativ:** Start Vercel+Supabase → migrer til Azure Norway East ved 50 kunder (da kan vi selge "norsk hosting" som feature).

**Anbefalt beslutningsdato:** Før Phase 1 kickoff
**Beslutningstaker:** Alem (CEO)

---

### ADR-003 — Autentisering og BankID

**Status:** OPEN — påvirker MVP-scope og trustnivå

**Spørsmål:** Email/passord + magic link (MVP) ELLER BankID fra dag 1?

| Alternativ | Fordel | Ulempe | Kostnad |
|-----------|--------|--------|---------|
| Email/passord + magic link | Rask MVP | Lavere tillit | ~0 |
| NextAuth.js / Clerk | God DX, sosial login | US-tjeneste, ingen BankID | ~300 NOK/mnd |
| BankID via Nets | Høy norsk tillit | 6–12 uker integrering, kostbart | ~5K NOK setup + per-auth |
| BankID via Signicat | Enklere enn Nets | Fortsatt kompleks | ~3K NOK/mnd |

**Anbefaling:** Email + magic link for MVP (Clerk), BankID i Phase 2 (etter first revenue).

**Norsk kontekst:** Norske SMBer forventer BankID for sensitive plattformer. Manglende BankID kan være salgsbarriere mot større kunder.

**Anbefalt beslutningsdato:** Uke 1 Phase 1
**Beslutningstaker:** Alem (CEO)

---

### ADR-004 — Monorepo vs Polyrepo

**Status:** OPEN (men sterkt anbefalt: Monorepo)

**Spørsmål:** Turborepo monorepo (Bilko-mønster) ELLER separate repos?

**Anbefaling:** Turborepo monorepo.

Begrunnelse:
- Delt kode mellom web + API + mobile (packages/)
- Bilko-erfaring direkte overførbar
- Enklere dependency management
- En PR for cross-cutting changes

---

### ADR-005 — Dataresidens og GDPR

**Status:** OPEN — juridisk viktig

**Spørsmål:** Kan vi bruke US-hostede tjenester (Vercel, Supabase) for norske HR-data?

**Juridisk kontekst:**
- GDPR tillater overføring til USA via Standard Contractual Clauses (SCCs)
- Schrems II gjør dette komplisert (men ikke umulig)
- Norske SMBer er ikke alltid klar over dette
- Konkurrenter (Simployer) er norsk-hostet — kan bli salgsargument mot oss

**Alternativer:**
1. US-hosting med SCCs (akseptabel juridisk, svakere salgsstory)
2. Norsk hosting fra dag 1 (Azure Norway East, Hetzner Falkenstein)
3. Hybrid — kode på Vercel, data på norsk server

**Anbefalt beslutningsdato:** Uke 2 Phase 1 (etter juridisk vurdering)
**Beslutningstaker:** Alem (CEO) — vurder juridisk rådgivning

---

## Allerede vedtatte beslutninger

| ADR | Beslutning | Dato |
|-----|-----------|------|
| Frontend | Next.js 15 + React 19 + TypeScript + Tailwind + shadcn/ui | 2026-02-24 |
| Database | PostgreSQL + Prisma + RLS multi-tenancy | 2026-02-24 |
| AI | Claude API (Haiku + Sonnet) | 2026-02-24 |
| Mobile (Phase 2) | React Native + Expo | 2026-02-24 |
| Monorepo-verktøy | Turborepo (følger Bilko) | 2026-02-24 |
| Referansekode | LumisCare (~/projects/client/lumiscare/) | 2026-02-24 |