luisfponce · luisfponce · Mar 9, 2026 · Mar 10, 2026
diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,7 @@ htmlcov/
 
 # Environment variables
 .env
+
+# Local runtime logs
+backend.log
+frontend.log
diff --git a/README.md b/README.md
@@ -9,3 +9,17 @@ docker build -t webapi:dev .; docker run --rm -p 8000:8000 webapi:dev
 ## Database diagram documentation
 
 The ORM model and relational mapping documentation for dbdiagram.io is available at [`plans/dbdiagram.md`](plans/dbdiagram.md).
+
+## Frontend v1
+
+A minimal frontend scaffold is available in [`frontend/`](frontend/).
+
+Run it locally:
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Detailed frontend docs are in [`frontend/README.md`](frontend/README.md).
diff --git a/frontend/.gitignore b/frontend/.gitignore
@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
diff --git a/frontend/README.md b/frontend/README.md
@@ -0,0 +1,47 @@
+# Frontend v1
+
+Minimal React + TypeScript + Vite frontend for login and prompts CRUD.
+
+## Requirements
+
+- Node.js 20.19+ recommended (project can build with warnings on Node 18 in this environment)
+- Backend API running at `http://127.0.0.1:8000`
+
+## Run locally
+
+```bash
+npm install
+npm run dev
+```
+
+Vite proxies `/api/*` requests to `http://127.0.0.1:8000` via [`vite.config.ts`](vite.config.ts).
+
+## Scripts
+
+- `npm run dev` start development server
+- `npm run build` typecheck and production build
+- `npm run lint` run ESLint
+- `npm run test` run Vitest tests
+
+## Environment
+
+Optional:
+
+- `VITE_API_BASE_URL=/api/v1`
+
+Default base URL is already `/api/v1` in [`src/lib/http/api-client.ts`](src/lib/http/api-client.ts).
+
+## Architecture summary
+
+- Routing in [`src/app/router.tsx`](src/app/router.tsx)
+- Providers in [`src/app/providers.tsx`](src/app/providers.tsx)
+- In-memory auth session in [`src/features/auth/auth-store.tsx`](src/features/auth/auth-store.tsx)
+- Login + user id resolution in [`src/features/auth/auth-service.ts`](src/features/auth/auth-service.ts)
+- Prompts CRUD in [`src/features/prompts/prompts-service.ts`](src/features/prompts/prompts-service.ts)
+- Design tokens and themes in [`src/styles/tokens.css`](src/styles/tokens.css), [`src/styles/themes.css`](src/styles/themes.css), and [`src/styles/base.css`](src/styles/base.css)
+
+## UX behavior
+
+- Session is memory-only; page reload requires login again
+- `user_id` is resolved after login by calling `/api/v1/users` and matching JWT username
+- Prompt list treats backend 404 (`No prompts found`) as empty state
diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js
@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])
diff --git a/frontend/index.html b/frontend/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>frontend</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>