phase-0: foundation, both apps boot end to end

Monorepo (pnpm workspaces) with two deployable apps and three pure packages.

apps/api (Hono on Node): Zod validated env that fails fast and names the problem,
Kysely factories for SQLite and Postgres chosen by DATABASE_URL scheme, portable
migrations covering the whole SPEC section 5 schema, Better Auth with the four
roles and seeded demo accounts, localized error envelope, /healthz and /readyz,
graceful SIGTERM drain. Dialect specific SQL is confined to the two factories.

apps/web (Next.js App Router): locale routed shell in es and en with a language
switcher, sign in screen, and a runtime /api proxy so the browser only ever sees
one origin and cookies stay first party.

packages/i18n ships both catalogs complete; es is generated from COPY.md and a
test re-derives it from the document on every run so it cannot drift.
packages/contracts holds the Zod schemas and the typed client the web app uses.

Verified: 43 vitest tests, 14 Playwright tests on mobile and desktop, typecheck
and lint clean, migrate and seed from a clean database, sign in through the proxy
with CSRF rejection of foreign origins.

Not verified here: docker compose. This user has no access to the docker socket.

RULES.md is absent from docs/, so packages/rules exports only RULES_VERSION and
no tax rule, check digit or deadline was invented. See DECISIONS.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/web/.env.example

@@ -0,0 +1,8 @@
+# apps/web environment. The web app holds no secrets: it renders UI and proxies /api.
+
+# Where the API can be reached from the web container. Used only server side, by the
+# Next rewrite. In k8s this is the api Service DNS name, for example http://api:4000.
+API_INTERNAL_URL=http://localhost:4000
+
+# Locale used before a visitor picks one. Must be a locale packages/i18n ships.
+NEXT_PUBLIC_DEFAULT_LOCALE=es

apps/web/Dockerfile

@@ -0,0 +1,35 @@
+# syntax=docker/dockerfile:1
+
+FROM node:22-slim AS build
+ENV PNPM_HOME=/pnpm PATH=/pnpm:$PATH
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN corepack enable
+WORKDIR /repo
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json ./
+COPY apps/api/package.json apps/api/
+COPY apps/web/package.json apps/web/
+COPY packages/contracts/package.json packages/contracts/
+COPY packages/i18n/package.json packages/i18n/
+COPY packages/rules/package.json packages/rules/
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
+
+COPY packages packages
+COPY apps/web apps/web
+COPY docs docs
+RUN pnpm --filter @impuestos/web build
+
+FROM node:22-slim AS runtime
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV PORT=3000 HOSTNAME=0.0.0.0
+WORKDIR /app
+
+# `output: standalone` emits a server with only the modules it actually imports.
+COPY --from=build --chown=node:node /repo/apps/web/.next/standalone ./
+COPY --from=build --chown=node:node /repo/apps/web/.next/static ./apps/web/.next/static
+
+USER node
+EXPOSE 3000
+
+CMD ["node", "apps/web/server.js"]

apps/web/app/[locale]/(app)/inicio/page.tsx

@@ -0,0 +1,52 @@
+import { isApiError } from '@impuestos/contracts';
+import { setRequestLocale } from 'next-intl/server';
+import { getT } from '@/i18n/t';
+import { redirect } from '@/i18n/navigation';
+import { Card } from '@/components/ui/card';
+import { LanguageSwitcher } from '@/components/language-switcher';
+import { serverApi } from '@/lib/api-server';
+
+/**
+ * Phase 0 shell. It exists to prove the whole chain end to end: browser to the Next
+ * rewrite, to the API, through the typed client, with the session cookie intact.
+ * The real dashboard (FLOWS.md Flow C) replaces this in phase 4.
+ */
+export default async function InicioPage({ params }: { params: Promise<{ locale: string }> }) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+  const t = await getT(locale);
+
+  const api = await serverApi();
+  const profile = await api.getProfile().catch((error: unknown) => {
+    if (!isApiError(error)) throw error;
+    // 404 is the documented state for a user who has not finished setup yet.
+    if (error.code === 'not_found') return null;
+    if (error.code === 'unauthorized') redirect({ href: '/login', locale });
+    throw error;
+  });
+
+  return (
+    <div className="mx-auto flex min-h-dvh max-w-2xl flex-col">
+      <header className="flex items-center justify-between px-5 py-4">
+        <h1 className="text-base font-semibold tracking-tight">{t('home.title')}</h1>
+        <LanguageSwitcher />
+      </header>
+
+      <main className="px-5 pb-16">
+        <Card className="space-y-2">
+          {profile ? (
+            <>
+              <p className="text-sm text-[var(--text-muted)]">{t('setup.fullName')}</p>
+              <p className="text-2xl font-semibold tracking-tight">{profile.fullName}</p>
+            </>
+          ) : (
+            <>
+              <h2 className="text-xl font-semibold tracking-tight">{t('setup.step1.title')}</h2>
+              <p className="text-sm text-[var(--text-muted)]">{t('setup.income.help')}</p>
+            </>
+          )}
+        </Card>
+      </main>
+    </div>
+  );
+}

apps/web/app/[locale]/(auth)/layout.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import { LanguageSwitcher } from '@/components/language-switcher';
+import { useT } from '@/i18n/t';
+
+export default function AuthLayout({ children }: { children: ReactNode }) {
+  const t = useT();
+  return (
+    <div className="flex min-h-dvh flex-col">
+      <header className="flex items-center justify-between px-5 py-4">
+        <span className="text-base font-semibold tracking-tight">{t('common.appName')}</span>
+        <LanguageSwitcher />
+      </header>
+      <main className="flex flex-1 items-center justify-center px-5 pb-16">
+        <div className="w-full max-w-sm">{children}</div>
+      </main>
+    </div>
+  );
+}

apps/web/app/[locale]/(auth)/login/login-form.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import { useMutation } from '@tanstack/react-query';
+import { useRouter } from '@/i18n/navigation';
+import { useT } from '@/i18n/t';
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { authClient } from '@/lib/auth-client';
+
+export function LoginForm() {
+  const t = useT();
+  const router = useRouter();
+
+  const signIn = useMutation({
+    mutationFn: async (form: { email: string; password: string }) => {
+      const { error } = await authClient.signIn.email(form);
+      if (error) throw new Error(error.message ?? 'sign_in_failed');
+    },
+    onSuccess: () => router.push('/inicio'),
+  });
+
+  return (
+    <Card className="space-y-6">
+      <h1 className="text-2xl font-semibold tracking-tight text-balance">{t('auth.login.title')}</h1>
+
+      <form
+        className="space-y-4"
+        onSubmit={(event) => {
+          event.preventDefault();
+          const data = new FormData(event.currentTarget);
+          signIn.mutate({
+            email: String(data.get('email') ?? ''),
+            password: String(data.get('password') ?? ''),
+          });
+        }}
+      >
+        <div className="space-y-1.5">
+          <Label htmlFor="email">{t('auth.register.email')}</Label>
+          <Input
+            id="email"
+            name="email"
+            type="email"
+            autoComplete="email"
+            required
+            aria-invalid={signIn.isError}
+          />
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="password">{t('auth.login.password')}</Label>
+          <Input
+            id="password"
+            name="password"
+            type="password"
+            autoComplete="current-password"
+            required
+            aria-invalid={signIn.isError}
+          />
+        </div>
+
+        {signIn.isError ? (
+          <p role="alert" className="text-sm text-overdue">
+            {t('auth.login.failed')}
+          </p>
+        ) : null}
+
+        <Button type="submit" size="lg" block disabled={signIn.isPending}>
+          {signIn.isPending ? t('common.loading') : t('auth.login.submit')}
+        </Button>
+      </form>
+    </Card>
+  );
+}

apps/web/app/[locale]/(auth)/login/page.tsx

@@ -0,0 +1,8 @@
+import { setRequestLocale } from 'next-intl/server';
+import { LoginForm } from './login-form';
+
+export default async function LoginPage({ params }: { params: Promise<{ locale: string }> }) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+  return <LoginForm />;
+}

apps/web/app/[locale]/layout.tsx

@@ -0,0 +1,49 @@
+import { isLocale } from '@impuestos/i18n';
+import type { Metadata } from 'next';
+import { Inter } from 'next/font/google';
+import { NextIntlClientProvider } from 'next-intl';
+import { setRequestLocale } from 'next-intl/server';
+import { getT } from '@/i18n/t';
+import { notFound } from 'next/navigation';
+import type { ReactNode } from 'react';
+import { Providers } from '@/components/providers';
+import { routing } from '@/i18n/routing';
+import '../globals.css';
+
+// Self hosted by next/font: no third party font request at runtime, which keeps the
+// CSP tight (SPEC.md section 14).
+const inter = Inter({ subsets: ['latin'], variable: '--font-inter', display: 'swap' });
+
+export function generateStaticParams() {
+  return routing.locales.map((locale) => ({ locale }));
+}
+
+export async function generateMetadata(props: {
+  params: Promise<{ locale: string }>;
+}): Promise<Metadata> {
+  const { locale } = await props.params;
+  const t = await getT(locale);
+  return { title: t('common.appName') };
+}
+
+export default async function LocaleLayout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{ locale: string }>;
+}) {
+  const { locale } = await params;
+  if (!isLocale(locale)) notFound();
+  setRequestLocale(locale);
+
+  return (
+    <html lang={locale} className={inter.variable} suppressHydrationWarning>
+      <body className="min-h-dvh font-sans antialiased">
+        <NextIntlClientProvider>
+          <Providers>{children}</Providers>
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}

apps/web/app/[locale]/page.tsx

@@ -0,0 +1,10 @@
+import { redirect } from '@/i18n/navigation';
+
+/**
+ * The landing page (FLOWS.md Flow A1) is built in phase 2. Until then the root goes
+ * straight to sign in so the shell is reachable.
+ */
+export default async function LandingPage({ params }: { params: Promise<{ locale: string }> }) {
+  const { locale } = await params;
+  redirect({ href: '/login', locale });
+}

apps/web/app/api/[...path]/route.ts

@@ -0,0 +1,68 @@
+import type { NextRequest } from 'next/server';
+
+/**
+ * Single origin proxy: the browser only ever talks to the web origin, and everything
+ * under /api is forwarded to the API container. Cookies stay first party, so there is
+ * no CORS anywhere in v1.
+ *
+ * SPEC-GAP: SPEC.md section 2 specifies Next rewrites for this. Next bakes rewrite
+ * destinations into the build manifest, which would make API_INTERNAL_URL a build time
+ * value and stop one image from running in both compose and k8s. A route handler reads
+ * it per request instead, which is what "all configuration via .env" requires.
+ */
+
+export const dynamic = 'force-dynamic';
+
+/** Set by the proxy or the runtime, never forwarded verbatim. */
+const STRIPPED_REQUEST_HEADERS = new Set([
+  'host',
+  'connection',
+  'content-length',
+  'transfer-encoding',
+  'accept-encoding',
+]);
+
+const STRIPPED_RESPONSE_HEADERS = new Set(['content-encoding', 'content-length', 'transfer-encoding']);
+
+function apiBaseUrl(): string {
+  return (process.env['API_INTERNAL_URL'] ?? 'http://localhost:4000').replace(/\/$/, '');
+}
+
+async function proxy(request: NextRequest): Promise<Response> {
+  const incoming = new URL(request.url);
+  const target = `${apiBaseUrl()}${incoming.pathname}${incoming.search}`;
+
+  const headers = new Headers();
+  request.headers.forEach((value, key) => {
+    if (!STRIPPED_REQUEST_HEADERS.has(key.toLowerCase())) headers.set(key, value);
+  });
+
+  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+  const upstream = await fetch(target, {
+    method: request.method,
+    headers,
+    redirect: 'manual',
+    ...(hasBody ? { body: request.body, duplex: 'half' } : {}),
+  } as RequestInit & { duplex?: 'half' });
+
+  const responseHeaders = new Headers();
+  upstream.headers.forEach((value, key) => {
+    const name = key.toLowerCase();
+    if (name === 'set-cookie') return;
+    if (!STRIPPED_RESPONSE_HEADERS.has(name)) responseHeaders.set(key, value);
+  });
+  // Session and CSRF cookies arrive as several Set-Cookie headers and must stay separate.
+  for (const cookie of upstream.headers.getSetCookie()) {
+    responseHeaders.append('set-cookie', cookie);
+  }
+
+  return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
+}
+
+export const GET = proxy;
+export const POST = proxy;
+export const PUT = proxy;
+export const PATCH = proxy;
+export const DELETE = proxy;
+export const HEAD = proxy;
+export const OPTIONS = proxy;

apps/web/app/globals.css

@@ -0,0 +1,96 @@
+@import 'tailwindcss';
+
+/*
+ * Design tokens, FLOWS.md section 1. Calm fintech: one accent, four semantic status
+ * colors used consistently everywhere, generous whitespace, big confident numbers.
+ */
+@theme {
+  --font-sans: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
+
+  /* Accent: deep teal. Primary actions and links only, nothing else. */
+  --color-accent-50: oklch(0.97 0.02 190);
+  --color-accent-100: oklch(0.93 0.04 190);
+  --color-accent-200: oklch(0.87 0.07 190);
+  --color-accent-400: oklch(0.68 0.11 190);
+  --color-accent-500: oklch(0.58 0.11 190);
+  --color-accent-600: oklch(0.48 0.1 191);
+  --color-accent-700: oklch(0.4 0.085 192);
+  --color-accent-900: oklch(0.27 0.055 194);
+
+  /* Status. positive = a favor, al dia. attention = action required.
+     overdue = missed deadlines and invalid documents ONLY, never "tax to pay".
+     neutral = everything else. */
+  --color-positive: oklch(0.62 0.14 155);
+  --color-positive-soft: oklch(0.95 0.04 155);
+  --color-attention: oklch(0.75 0.15 78);
+  --color-attention-soft: oklch(0.96 0.05 85);
+  --color-overdue: oklch(0.58 0.19 25);
+  --color-overdue-soft: oklch(0.95 0.04 25);
+  --color-neutral-fg: oklch(0.45 0.02 250);
+
+  --radius-card: 1rem;
+}
+
+/* Explicit toggle wins over the system preference in both directions (FLOWS.md
+   section 1: dark mode from system preference plus a toggle). */
+@custom-variant dark (&:where([data-theme='dark'], [data-theme='dark'] *));
+
+:root {
+  --surface: oklch(0.99 0.003 250);
+  --surface-raised: oklch(1 0 0);
+  --border-subtle: oklch(0.92 0.005 250);
+  --text: oklch(0.22 0.015 255);
+  --text-muted: oklch(0.52 0.015 255);
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) {
+    --surface: oklch(0.18 0.012 255);
+    --surface-raised: oklch(0.23 0.014 255);
+    --border-subtle: oklch(0.31 0.012 255);
+    --text: oklch(0.96 0.004 250);
+    --text-muted: oklch(0.72 0.012 255);
+    color-scheme: dark;
+  }
+}
+
+:root[data-theme='dark'] {
+  --surface: oklch(0.18 0.012 255);
+  --surface-raised: oklch(0.23 0.014 255);
+  --border-subtle: oklch(0.31 0.012 255);
+  --text: oklch(0.96 0.004 250);
+  --text-muted: oklch(0.72 0.012 255);
+  color-scheme: dark;
+}
+
+@layer base {
+  * {
+    border-color: var(--border-subtle);
+  }
+
+  body {
+    background-color: var(--surface);
+    color: var(--text);
+    -webkit-font-smoothing: antialiased;
+  }
+
+  /* Every money figure is tabular. FLOWS.md section 1. */
+  .tnum {
+    font-variant-numeric: tabular-nums;
+    font-feature-settings: 'tnum';
+  }
+}
+
+/* Motion is purposeful and always interruptible. This disables the non essential
+   kind globally, which the GSAP context mirrors. */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}

apps/web/app/healthz/route.ts

@@ -0,0 +1,6 @@
+/** Liveness for the web container. Renders nothing and never calls the API. */
+export const dynamic = 'force-dynamic';
+
+export function GET(): Response {
+  return Response.json({ ok: true });
+}

apps/web/next-env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+import "./.next/types/root-params.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/web/next.config.ts

@@ -0,0 +1,13 @@
+import createNextIntlPlugin from 'next-intl/plugin';
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+  // The workspace packages ship TypeScript source with no build step.
+  transpilePackages: ['@impuestos/contracts', '@impuestos/i18n'],
+  output: 'standalone',
+  // /api is proxied at runtime by app/api/[...path]/route.ts rather than by a rewrite,
+  // so API_INTERNAL_URL stays a runtime setting. See the comment in that file.
+};
+
+export default createNextIntlPlugin('./src/i18n/request.ts')(nextConfig);

apps/web/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@impuestos/web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev --port 3000",
+    "build": "next build",
+    "start": "next start --port 3000",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@impuestos/contracts": "workspace:*",
+    "@impuestos/i18n": "workspace:*",
+    "@tanstack/react-query": "^5.102.8",
+    "better-auth": "^1.7.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.40.0",
+    "next": "^16.3.4",
+    "next-intl": "^4.14.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tailwind-merge": "^3.6.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.3",
+    "@types/node": "^26.4.1",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3"
+  }
+}

apps/web/postcss.config.mjs

@@ -0,0 +1,3 @@
+export default {
+  plugins: { '@tailwindcss/postcss': {} },
+};

apps/web/proxy.ts

@@ -0,0 +1,10 @@
+import createMiddleware from 'next-intl/middleware';
+import { routing } from './src/i18n/routing';
+
+export default createMiddleware(routing);
+
+export const config = {
+  // Everything except /api (forwarded to the API by the rewrite), Next internals and
+  // static files. Locale routing must not touch API requests.
+  matcher: ['/((?!api|healthz|_next|_vercel|.*\\..*).*)'],
+};

apps/web/src/components/language-switcher.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+import { SUPPORTED_LOCALES, type Locale } from '@impuestos/i18n';
+import { Globe } from 'lucide-react';
+import { useLocale } from 'next-intl';
+import { useTransition } from 'react';
+import { usePathname, useRouter } from '@/i18n/navigation';
+import { useT } from '@/i18n/t';
+
+const LABEL_KEY = { es: 'common.languageEs', en: 'common.languageEn' } as const;
+
+/**
+ * Compact globe menu, header on marketing and auth screens (FLOWS.md section 1).
+ * Switching keeps the current page: the locale lives in the URL.
+ *
+ * A native select rather than a popover: it is one dependency fewer, and the platform
+ * control is the better mobile and keyboard experience for a two item choice.
+ */
+export function LanguageSwitcher() {
+  const t = useT();
+  const locale = useLocale();
+  const router = useRouter();
+  const pathname = usePathname();
+  const [isPending, startTransition] = useTransition();
+
+  return (
+    <label className="relative inline-flex items-center gap-2 text-sm text-[var(--text-muted)]">
+      <Globe aria-hidden className="size-4" />
+      <span className="sr-only">{t('common.language')}</span>
+      <select
+        aria-label={t('common.language')}
+        className="cursor-pointer appearance-none rounded-full bg-transparent py-1 pr-6 pl-1 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent-600"
+        disabled={isPending}
+        value={locale}
+        onChange={(event) => {
+          const next = event.target.value as Locale;
+          startTransition(() => {
+            router.replace(pathname, { locale: next });
+          });
+        }}
+      >
+        {SUPPORTED_LOCALES.map((code) => (
+          <option key={code} value={code}>
+            {t(LABEL_KEY[code])}
+          </option>
+        ))}
+      </select>
+      <svg
+        aria-hidden
+        className="pointer-events-none absolute right-1 size-3"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        viewBox="0 0 24 24"
+      >
+        <path d="m6 9 6 6 6-6" strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+    </label>
+  );
+}

apps/web/src/components/providers.tsx

@@ -0,0 +1,15 @@
+'use client';
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useState, type ReactNode } from 'react';
+
+/** All server state goes through TanStack Query. One client per browser session. */
+export function Providers({ children }: { children: ReactNode }) {
+  const [client] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: { queries: { staleTime: 30_000, retry: 1, refetchOnWindowFocus: false } },
+      }),
+  );
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}

apps/web/src/components/ui/button.tsx

@@ -0,0 +1,30 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { ButtonHTMLAttributes } from 'react';
+import { cn } from '@/lib/utils';
+
+const button = cva(
+  'inline-flex items-center justify-center gap-2 rounded-full font-medium transition-colors ' +
+    'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent-600 ' +
+    'disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-accent-600 text-white hover:bg-accent-700',
+        secondary: 'border bg-[var(--surface-raised)] hover:bg-accent-50',
+        ghost: 'hover:bg-accent-50',
+      },
+      size: {
+        md: 'h-11 px-5 text-sm',
+        lg: 'h-13 px-6 text-base',
+      },
+      block: { true: 'w-full', false: '' },
+    },
+    defaultVariants: { variant: 'primary', size: 'md', block: false },
+  },
+);
+
+export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof button>;
+
+export function Button({ className, variant, size, block, ...props }: ButtonProps) {
+  return <button className={cn(button({ variant, size, block }), className)} {...props} />;
+}

apps/web/src/components/ui/card.tsx

@@ -0,0 +1,14 @@
+import type { HTMLAttributes } from 'react';
+import { cn } from '@/lib/utils';
+
+export function Card({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn(
+        'rounded-2xl border bg-[var(--surface-raised)] p-6 shadow-[0_1px_2px_rgba(0,0,0,0.04)]',
+        className,
+      )}
+      {...props}
+    />
+  );
+}

apps/web/src/components/ui/input.tsx

@@ -0,0 +1,18 @@
+import type { InputHTMLAttributes } from 'react';
+import { cn } from '@/lib/utils';
+
+export function Input({ className, ...props }: InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <input
+      className={cn(
+        'h-12 w-full rounded-2xl border bg-[var(--surface-raised)] px-4 text-base',
+        'placeholder:text-[var(--text-muted)]',
+        'focus-visible:border-accent-500 focus-visible:outline-2 focus-visible:outline-offset-0',
+        'focus-visible:outline-accent-500/40',
+        'aria-invalid:border-overdue',
+        className,
+      )}
+      {...props}
+    />
+  );
+}

apps/web/src/components/ui/label.tsx

@@ -0,0 +1,11 @@
+import type { LabelHTMLAttributes } from 'react';
+import { cn } from '@/lib/utils';
+
+export function Label({ className, ...props }: LabelHTMLAttributes<HTMLLabelElement>) {
+  return (
+    <label
+      className={cn('block text-sm font-medium text-[var(--text-muted)]', className)}
+      {...props}
+    />
+  );
+}

apps/web/src/i18n/navigation.ts

@@ -0,0 +1,5 @@
+import { createNavigation } from 'next-intl/navigation';
+import { routing } from './routing';
+
+/** Locale aware Link and router. Switching language keeps the current page. */
+export const { Link, redirect, usePathname, useRouter, getPathname } = createNavigation(routing);

apps/web/src/i18n/request.ts

@@ -0,0 +1,8 @@
+import { DEFAULT_LOCALE, catalogs, isLocale, unflatten } from '@impuestos/i18n';
+import { getRequestConfig } from 'next-intl/server';
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  const requested = await requestLocale;
+  const locale = isLocale(requested) ? requested : DEFAULT_LOCALE;
+  return { locale, messages: unflatten(catalogs[locale]) };
+});

apps/web/src/i18n/routing.ts

@@ -0,0 +1,9 @@
+import { DEFAULT_LOCALE, SUPPORTED_LOCALES } from '@impuestos/i18n';
+import { defineRouting } from 'next-intl/routing';
+
+/** Adding a locale is a catalog file plus SUPPORTED_LOCALES. This picks it up for free. */
+export const routing = defineRouting({
+  locales: [...SUPPORTED_LOCALES],
+  defaultLocale: DEFAULT_LOCALE,
+  localePrefix: 'always',
+});

apps/web/src/i18n/t.ts

@@ -0,0 +1,22 @@
+import { type MessageKey, resolveKey } from '@impuestos/i18n';
+import { useTranslations } from 'next-intl';
+import { getTranslations } from 'next-intl/server';
+
+type Params = Record<string, string | number | Date>;
+
+/**
+ * Thin wrapper over next-intl so components address messages by their COPY.md key.
+ *
+ * next-intl walks a nested message tree, and one COPY.md key (`decl.approve`) is both a
+ * message and a namespace. `resolveKey` maps those onto their real path so the calling
+ * code never has to know.
+ */
+export function useT(): (key: MessageKey, params?: Params) => string {
+  const t = useTranslations();
+  return (key, params) => t(resolveKey(key), params);
+}
+
+export async function getT(locale: string): Promise<(key: MessageKey, params?: Params) => string> {
+  const t = await getTranslations({ locale });
+  return (key, params) => t(resolveKey(key), params);
+}

apps/web/src/lib/api-server.ts

@@ -0,0 +1,15 @@
+import { createApiClient } from '@impuestos/contracts';
+import { headers } from 'next/headers';
+
+/**
+ * Server side client for Server Components. It calls the API container directly and
+ * forwards the incoming cookie, since a server render has no browser to do it.
+ */
+export async function serverApi() {
+  const incoming = await headers();
+  const cookie = incoming.get('cookie');
+  return createApiClient({
+    baseUrl: process.env['API_INTERNAL_URL'] ?? 'http://localhost:4000',
+    ...(cookie ? { headers: { cookie } } : {}),
+  });
+}

apps/web/src/lib/api.ts

@@ -0,0 +1,7 @@
+import { createApiClient } from '@impuestos/contracts';
+
+/**
+ * Browser client. The base URL is empty on purpose: requests go to `/api` on the web
+ * origin and the Next rewrite forwards them, so the session cookie stays first party.
+ */
+export const api = createApiClient();

apps/web/src/lib/auth-client.ts

@@ -0,0 +1,13 @@
+'use client';
+
+import { adminClient } from 'better-auth/client/plugins';
+import { createAuthClient } from 'better-auth/react';
+
+/**
+ * Auth runs entirely in the API. This is the client half only: it posts to /api/auth,
+ * which the web app proxies. No better-auth server code exists in this app.
+ */
+export const authClient = createAuthClient({
+  basePath: '/api/auth',
+  plugins: [adminClient()],
+});

apps/web/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

apps/web/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "jsx": "preserve",
+    "allowJs": true,
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}