# Co-design Frontend

Nuxt 4 frontend for the Co-design assistant. The app provides:

- authenticated project workspace and chat experience
- AI-assisted project threads and template generation flows
- a project knowledge hub and a user guide area
- server-side proxy routes under `/services/*` for auth and backend API access

## Stack

- Nuxt `4.x`
- Vue `3.x`
- TypeScript
- Nuxt UI
- Nuxt Image
- Nuxt Icon
- Pinia
- `@sidebase/nuxt-auth` (Keycloak via Auth.js)
- AI SDK (`@ai-sdk/vue`, `@ai-sdk/openai`)

## Project Structure

- `app/`: UI pages, components, composables, Pinia stores
- `server/routes/services/`: server endpoints proxied to auth/backend services
- `server/middleware/auth.ts`: protects `/services/*` routes (except auth public paths)
- `server/utils/`: auth context and upstream API helpers for proxy routes
- `public/`: static assets
- `docker-compose.yml`, `Dockerfile`: containerized run/build

## Prerequisites

- Node.js `>= 20` (project Docker image uses Node 24)
- npm
- Keycloak environment values
- Backend API reachable from `NUXT_AI_BASE_URL`

## Setup

1. Install dependencies.

```bash
npm install
```

2. Create local environment file.

On macOS/Linux:

```bash
cp .env.example .env
```

On Windows PowerShell:

```powershell
Copy-Item .env.example .env
```

3. Fill required variables in `.env`.

## Environment Variables

Current setup requires or recognizes the following variables:

- `NUXT_PUBLIC_KEYCLOAK_ISSUER`: Keycloak issuer URL
- `NUXT_PUBLIC_KEYCLOAK_CLIENT_ID`: Keycloak client id
- `NUXT_KEYCLOAK_CLIENT_SECRET`: Keycloak client secret
- `NUXT_AUTH_SECRET`: Auth.js secret used by `NuxtAuthHandler`
- `NUXT_AUTH_ORIGIN`: auth origin (example in `.env.example`: `http://localhost:3000/services/auth`)
- `NUXT_AI_BASE_URL`: backend base URL used by server proxy routes
- `FRONTEND_PORT`: used in Docker Compose mapping
- `ENV`: used in Docker Compose image/container naming and env file selection

## Run Locally

Development server:

```bash
npm run dev
```

Build production bundle:

```bash
npm run build
```

Preview built app:

```bash
npm run preview
```

Default local URL is usually `http://localhost:3000` unless changed by env/port config.

Format the codebase:

```bash
npm run format
```

## Docker

Build and run with compose:

```bash
docker compose up --build
```

Notes:

- `docker-compose.yml` expects `ENV` and `FRONTEND_PORT`.
- It loads `.env.ci.${ENV}` through `env_file`.
- The runtime container exposes ports `3000` and `3001`; compose binds `FRONTEND_PORT` to the app `PORT`.

## Frontend Routes

Defined pages currently include:

- `/` (`app/pages/index.vue`): home and project entry
- `/project/[id]` (`app/pages/project/[id]/index.vue`): main chat workspace
- `/project/[id]/knowledge-hub` (`app/pages/project/[id]/knowledge-hub.vue`): templates/knowledge base
- `/project/[id]/settings` (`app/pages/project/[id]/settings.vue`): project editing, export, and members management
- `/about-co-design` (`app/pages/about-co-design/index.vue`): user guide content

## Server Routes

Main route groups under `server/routes/services/`:

- `/services/auth/*` -> auth handler (`server/routes/services/auth/[...].ts`)
- `/services/diagnosis/questions/pages` -> diagnosis question pages
- `/services/diagnosis/flash` and `/services/diagnosis/flash/:id/convert` -> flash diagnosis flows
- `/services/diagnosis/:id/rerun` and `/services/diagnosis/project/:id` -> diagnosis rerun and project conversion
- `GET|POST /services/projects`
- `POST /services/projects/join`
- `GET /services/projects/user`
- `GET|PATCH|DELETE /services/projects/:projectId`
- `GET|POST /services/projects/:projectId/invite`
- `GET|PATCH /services/projects/:projectId/members`
- `POST /services/projects/:projectId/members/:memberId/manage`
- `GET /services/projects/:projectId/notifications`
- `GET|PATCH /services/projects/:projectId/project_user`
- `GET /services/projects/:projectId/export`
- `GET|POST|PATCH /services/projects/:projectId/template`
- `GET|POST|PATCH /services/projects/:projectId/chat`
- `GET|PATCH /services/projects/:projectId/chat/:threadId`
- `GET|POST /services/projects/:projectId/chat/:threadId/messages`

All `/services/*` routes are protected by `server/middleware/auth.ts` except public auth endpoints.

## Chat and State Overview

- Chat UI is page-scoped per project/thread and uses `@ai-sdk/vue` (`app/store/chat.ts`).
- Thread/project state is managed in Pinia (`app/store/project.ts`, `app/store/main.ts`, `app/store/chat.ts`).
- Template and project operations are executed via app composables/stores through `/services/*` routes.

## VS Code Recommendations

Recommended extensions:

- ESLint (`dbaeumer.vscode-eslint`)
- Tailwind CSS IntelliSense (`bradlc.vscode-tailwindcss`)
- PostCSS Language Support (`csstools.postcss`)
- Vue extension pack / Volar-based support

## Troubleshooting

- `401 Unauthorized` from `/services/*`: ensure Keycloak values are set and login completed, then verify `NUXT_AUTH_ORIGIN`, issuer, and client settings.
- App loads but no project/chat data: verify backend reachability at `NUXT_AI_BASE_URL`.
- `npm run preview` fails: run `npm run build` first.

## Scripts

From `package.json`:

- `npm run dev`: start dev server
- `npm run build`: build app
- `npm run generate`: static generation
- `npm run preview`: preview built app
- `npm run format`: run Prettier on the repository
- `npm run postinstall`: `nuxt prepare`

## Versioning

Effective app versioning with npm:

### Prepare a release version

Use npm version to automatically bump the version and create a git tag:

```bash
npm version patch -m "Upgrade to %s for production"
```

- `%s` is automatically replaced with the new version number
- Use `minor` or `major` instead of `patch` to increment accordingly

```bash
git checkout main
git merge dev

# Push code to main
git push origin main

# Push the git tag that npm created
git push origin --tags
```

This workflow ensures consistent versioning across npm registry and git history.