Lead Management Frontend

SvelteKit-based dashboard for managing customer leads, built on a GraphQL backend. It ships with authenticated flows, lead lifecycle tooling, and automated form validation driven from the GraphQL schema.

Table of contents

• Overview
• Tech stack
• Quick start
• Environment variables
• Available npm scripts
• Code generation pipeline
• Application flows
• Documentation and project layout
• Testing strategy

Overview

• Dashboard consumes the GraphQL API from the companion backend (lead-management-backend).
• Lead list supports create, edit, search, filter, and history review with optimistic UI feedback.
• Forms and data fetching stay type safe through generated TypeScript types and Zod schemas.
• Authentication persists access and refresh tokens, handling forced password resets when required by the API.

Tech stack

• SvelteKit for routing, layouts.
• @apollo/client plus @tanstack/svelte-query for GraphQL transport, caching, and request lifecycle management (src/lib/graphql/client.ts).
• Zod-based form validation generated from GraphQL input objects (src/lib/forms/formSchemas.ts).
• Tailwind CSS and bits-ui (through shadcn-svelte) component primitives for styling.
• Vitest for unit testing and Playwright for end-to-end coverage with mocked GraphQL responses.

Quick start

1. Ensure Node.js 20+ and npm are installed.
2. Install dependencies:

   npm install
   

3. Create a local environment file and configure the backend endpoint:

   cp .env.example .env
   # edit .env as needed
   

4. Run the development server:

   npm run dev
   

   The app is served at http://localhost:5173 by default. Start the backend project before signing in.

Environment variables

• VITE_GRAPHQL_ENDPOINT - GraphQL HTTP endpoint used by the Apollo client. Defaults to http://localhost:8080/query when unset (see src/lib/graphql/client.ts).

Available npm scripts

• npm run dev - start the Vite dev server with hot module reloading.
• npm run build - generate a production build in build/ using the SvelteKit Node adapter.
• npm run preview - serve the production build locally to validate deployment artifacts.
• npm run prepare - synchronize SvelteKit manifest data (invoked automatically by npm when installing).
• npm run check / npm run check:watch - run svelte-check for type-safe template validation (optionally in watch mode).
• npm run format - format the entire repository using Prettier with import sorting.
• npm run lint - run Prettier in check mode plus ESLint for static analysis.
• npm run test:unit - execute Vitest suites (DOM and logic units under src/).
• npm run test:e2e - execute Playwright scenarios under e2e/.
• npm run test - run unit tests, then Playwright suites for a full smoke test.
• npm run codegen - refresh generated GraphQL types and Zod form schemas (see below).

Code generation pipeline

• Configuration lives in codegen.mjs, pointing the generator at src/lib/graphql/schema.graphqls and document files in src/lib/graphql/**/*.{graphql,gql}.
• Running npm run codegen performs two steps:
  1. graphql-codegen produces strongly typed operations in src/lib/graphql/generated.ts, including TypedDocumentNode helpers the Apollo client and Svelte Query rely on.
  2. scripts/generate-form-schemas.ts parses the schema, applies custom @formField directives, and emits Zod factories in src/lib/forms/formSchemas.ts. These shapes enforce the same constraints on the client that the API enforces server-side (required fields, formatting rules, cross-field validation).
• Re-run the script whenever the GraphQL schema or .graphql documents change to keep types and forms in sync.

Application flows

• Authentication - /login authenticates via the login mutation. When the API responds with requiresPasswordReset, the UI collects a new password and calls completePasswordReset. Tokens are stored and refreshed automatically (e2e/auth-flow.spec.ts).
• Lead management - /dashboard/leads lists leads with search, filter, auditing, and CRUD dialogs. Mutations include CreateLead, UpdateLead, and LeadHistory queries for change tracking (e2e/leads-flow.spec.ts).
• User management - Admins manage team members on /dashboard/users, including onboarding new users, privilege changes, and safeguards against self-demotion. Non-admins are denied access (e2e/users-flow.spec.ts).
• Profile management - Users can update profile details and passwords and sign out from the dashboard header (e2e/profile-flow.spec.ts).

Documentation and project layout

• API contract: src/lib/graphql/schema.graphqls defines types, mutations, and form directives used by the generator.
• Generated client types: src/lib/graphql/generated.ts (do not edit manually).
• Generated form schemas: src/lib/forms/formSchemas.ts (referenced by UI forms under src/lib/forms/).
• Route structure: src/routes maps Svelte components to application pages (+layout.svelte, +page.svelte, etc.).
• Playwright helpers and fixtures: e2e/support/ including graphqlMock.ts for queueing mocked responses.
• Build output: build/ (created by npm run build) ready for server deployment via the Node adapter.

Testing strategy

• Unit tests live alongside source files (for example src/lib/forms/errorUtils.spec.ts) and run with npm run test:unit. These cover reusable logic and store modules.
• End-to-end tests under e2e/ leverage Playwright plus a GraphQL mock server (createGraphQLMock) to validate user journeys without hitting a live backend.
• npm run test is the recommended CI entry point to execute both layers. Consider running npm run lint and npm run check in pipelines to catch type or lint regressions before runtime.