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.

npm install

  1. Create local environment file.

On macOS/Linux:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

  1. 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:

npm run dev

Build production bundle:

npm run build

Preview built app:

npm run preview

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

Format the codebase:

npm run format

Docker

Build and run with compose:

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:

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

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.