AI-DLC: inception en ontwerp voor redesign B/E met contactformulier

Requirements, application design (incl. concept-API-contract voor het contactformulier), units en functional design voor U1.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-09 21:06:25 +01:00
co-authored by Claude Sonnet 5.5
parent ad4671334a
commit 1047c738b5
34 changed files with 2248 additions and 3 deletions
@@ -0,0 +1,26 @@
# API Documentation
## REST APIs (consumed)
### Offerings
- **Method**: GET
- **Path**: `{VITE_API_BASE_URL ?? ''}/api/v1/offerings`
- **Purpose**: package cards for PackagesSection
- **Request**: none
- **Response**: JSON array of `PackageCardData`; contract documented in `aidlc-docs/features/react-frontend/construction/react-frontend-app/functional-design/packages-api-handoff.md`
### Sentry tunnel
- **Method**: POST `/sentry-tunnel` (proxied by nginx; vite dev proxy locally)
## REST APIs (provided by this repo)
None. No contact/form endpoint exists yet; `ContactSection` uses `mailto:`.
## Internal APIs
### useTheme()
- **Methods**: `{ theme: 'red' | 'purple', toggleTheme() }`; throws outside ThemeProvider.
### usePackagesQuery()
- **Return**: TanStack Query result with `data: PackageCardData[]`.
## Data Models
### PackageCardData
- **Fields**: `id, slug, title, description, price, priceNote, features[], ctaLabel, featured?`
- **Validation**: none client-side (trusts API).
@@ -0,0 +1,75 @@
# System Architecture
## System Overview
Static single-page React application (Vite build) served as static files behind nginx on Raspberry Pis (test and production). One route (`/`), hash-based history. Dynamic data: packages via same-origin `GET /api/v1/offerings`. Monitoring: Sentry (via `/sentry-tunnel`) and self-hosted Umami.
## Architecture Diagram
```mermaid
graph TD
Browser[Browser] --> RP[Reverse-proxy Pi nginx]
RP --> WS[Web server Pi - static dist/]
RP --> API[CMS and API backend]
RP --> Sentry[Sentry tunnel]
Browser --> Umami[Umami analytics]
subgraph SPA[React SPA]
Root[__root route + RootLayout] --> Nav
Root --> Landing[LandingPage]
Root --> Footer
Landing --> Hero
Landing --> About
Landing --> Packages[PackagesSection + usePackagesQuery]
Landing --> Process
Landing --> Contact[ContactSection]
Nav --> Toggle[ThemeToggle]
Toggle --> TP[ThemeProvider]
end
Packages -->|fetch| API
classDef infra fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef ui fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef ext fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
class RP,WS,API infra;
class Root,Nav,Landing,Footer,Hero,About,Packages,Process,Contact,Toggle,TP ui;
class Sentry,Umami,Browser ext;
```
Text alternative: browser reaches nginx reverse proxy, which serves the static React bundle and proxies the API and Sentry tunnel; inside the SPA a root layout wraps nav, landing sections and footer.
## Component Descriptions
### ThemeProvider / tokens.ts / index.css
- **Purpose**: Theme state. `ThemeName = 'red' | 'purple'`, stored in localStorage key `slp-software-theme`, applied as class `theme-red`/`theme-purple` on `<html>`; colors are CSS variables mapped to Tailwind colors (`bg`, `surface`, `line`, `text`, `muted`, `accent`...).
- **Dependencies**: React context only.
- **Type**: Application
### Nav / Footer / RootLayout
- **Purpose**: Sticky nav (anchor links, CTA, ThemeToggle, mobile menu), footer, layout shell incl. UmamiAnalytics and SentryTestButton.
- **Type**: Application
### Landing feature (`src/features/landing`)
- **Purpose**: Sections and static content (`data/content.ts`), packages query hook.
- **Type**: Application
## Data Flow
```mermaid
sequenceDiagram
box rgba(99,179,237,0.4) Client
participant U as Visitor
participant P as PackagesSection
end
box rgba(154,230,180,0.4) Server
participant A as API offerings
end
U->>P: open page
P->>A: GET /api/v1/offerings
A-->>P: PackageCardData array
P-->>U: render cards or error text
```
## Integration Points
- **External APIs**: `GET {VITE_API_BASE_URL}/api/v1/offerings` (packages); Sentry envelope via `/sentry-tunnel`.
- **Databases**: none in this repo.
- **Third-party Services**: Sentry, Umami (self-hosted).
## Infrastructure Components
- **Deployment Model**: Gitea Actions (`continuous_integration.yaml`, `deploy.yaml`), static bundle on Raspberry Pi nginx; test and production environments.
- **Networking**: reverse-proxy Pi in front of web-server Pi (see feature react-frontend operations docs).
@@ -0,0 +1,34 @@
# Business Overview
## Business Context Diagram
```mermaid
graph LR
V[Visitor / prospect] --> S[slpsoftware.nl marketing site]
S --> O[Offerings API /api/v1/offerings]
S --> M[mailto link info@slpsoftware.nl]
B[Bryan Slop - SLP Software] --> M
O --> C[CMS and API - sibling repo]
classDef actor fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef app fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef ext fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
class V,B actor;
class S app;
class O,M,C ext;
```
Text alternative: visitors use the marketing site, which loads packages from the offerings API (hosted by the CMS and API repo) and currently hands contact requests off through a mailto link.
## Business Description
- **Business Description**: Marketing site of SLP Software, a one-person web and .NET development business (Bryan Slop). Goal: explain the offering, show packages with fixed prices, and get prospects to start a project.
- **Business Transactions**: (1) Visitor reads about the business; (2) Visitor browses packages (data from API); (3) Visitor reads the 3-step process; (4) Visitor requests a project (today: opens a mail client via mailto); (5) Visitor switches colour theme.
- **Business Dictionary**: *Pakket* = fixed-scope, fixed-price offering; *Maatwerk* = custom work quoted after intake; *Werkwijze* = process (intake, build, live).
## Component Level Business Descriptions
### Landing page (Hero, About, Packages, Process, Contact)
- **Purpose**: Single-page storefront.
- **Responsibilities**: Messaging, package presentation, call to action.
### Theme system
- **Purpose**: Let visitors choose red or purple dark theme.
- **Responsibilities**: Persist choice, apply CSS variable set.
@@ -0,0 +1,21 @@
# Code Quality Assessment
## Test Coverage
- **Overall**: Fair (23 tests at last recorded run; coverage % not measured)
- **Unit Tests**: Present for theme, nav, shared components, packages section
- **Integration Tests**: None
## Code Quality Indicators
- **Linting**: Configured (ESLint + typescript-eslint)
- **Code Style**: Consistent (Prettier)
- **Documentation**: Good (README, aidlc-docs)
## Technical Debt
- `ThemeName` is a closed union of two colour themes; adding light/dark and a variant (B vs E) needs a model change (theme = mode x variant).
- Design is heavily tied to the current dark red/purple look; B and E need new tokens, fonts (Archivo, Open Sans, Trebuchet/Verdana, VT323) and section components.
- `ContactSection` is mailto only; no form, validation or submit endpoint.
- `SKELETON_COUNT = 3` and `sm:grid-cols-3` hard-code three packages.
## Patterns and Anti-patterns
- **Good Patterns**: semantic Tailwind colors via CSS variables, feature folders, guarded localStorage access.
- **Anti-patterns**: none significant.
@@ -0,0 +1,38 @@
# Code Structure
## Build System
- **Type**: pnpm + Vite 5 + `tsc -b`
- **Configuration**: `vite.config.ts` (react plugin, `__APP_VERSION__` define, dev proxy `/sentry-tunnel`, vitest jsdom), `tailwind.config.ts`, `postcss.config.js`, `tsconfig*.json`, `eslint.config.js`, `.prettierrc`
## Key Modules
Entry: `index.html` → `src/main.tsx` (Sentry init, RouterProvider) → `src/router.tsx` (hash history) → `src/routes/__root.tsx` (ThemeProvider + RootLayout) → `src/routes/index.tsx` (LandingPage).
### Existing Files Inventory
- `src/main.tsx` - bootstrap, Sentry
- `src/router.tsx`, `src/routes/__root.tsx`, `src/routes/index.tsx` - routing
- `src/fonts.ts` - @fontsource imports (Instrument Sans, Sora, JetBrains Mono)
- `src/index.css` - Tailwind layers, `.theme-red`/`.theme-purple` variable sets, caret animation
- `src/theme/ThemeProvider.tsx`, `src/theme/tokens.ts` - theme context, ids, storage key
- `src/components/layout/Nav.tsx`, `Footer.tsx`, `RootLayout.tsx` - shell
- `src/components/ui/ThemeToggle.tsx` - round swatch button
- `src/components/shared/UmamiAnalytics.tsx`, `ErrorBoundary.tsx`, `SentryTestButton.tsx` - cross-cutting
- `src/features/landing/pages/LandingPage.tsx` - section composition (Hero, About, Packages, Process, Contact)
- `src/features/landing/components/*` - Hero, AboutSection (photo, WebP variants in `public/`), PackagesSection, PackageCard, PackageCardSkeleton, ProcessSection, ProcessStep, ContactSection (mailto only)
- `src/features/landing/data/content.ts` - nav links, hero, packages seed, process steps, about, contact info
- `src/features/landing/hooks/usePackagesQuery.ts` - TanStack Query fetch of offerings
- `src/lib/queryClient.ts`, `src/utils/scrollToHash.ts`, `src/test/setup.ts`
- Tests: `Nav.test.tsx`, `ErrorBoundary.test.tsx`, `SentryTestButton.test.tsx`, `UmamiAnalytics.test.tsx`, `ThemeProvider.test.tsx`, `PackagesSection.test.tsx`
- `References/` - original static HTML designs (purple and red)
## Design Patterns
### CSS-variable theming
- **Location**: `index.css`, `tailwind.config.ts`
- **Purpose**: switch theme by swapping a class on `<html>`; components use semantic Tailwind colors.
- **Implementation**: `ThemeName` union + `themeClassName()`.
### Feature folder
- **Location**: `src/features/landing`
- **Purpose**: group components/data/hooks by feature.
## Critical Dependencies
- react 18.3, @tanstack/react-router 1.79 (hash history), @tanstack/react-query 5, tailwindcss 3.4, @sentry/react 10, @fontsource fonts.
@@ -0,0 +1,21 @@
# Component Inventory
## Application Packages
- slp-software-frontend (this repo) - React SPA marketing site
## Infrastructure Packages
- `.gitea/workflows/continuous_integration.yaml`, `deploy.yaml` - Gitea Actions CI/CD
- nginx example configs in `aidlc-docs/features/react-frontend/operations/deployment/nginx/`
## Shared Packages
- none (sibling repo `AndreaSlopFotografie-cms-api-foundation` hosts CMS/API, external to this workspace)
## Test Packages
- Vitest + Testing Library co-located `__tests__` folders (6 test files)
## Total Count
- **Total Packages**: 1
- **Application**: 1
- **Infrastructure**: 0 (config only)
- **Shared**: 0
- **Test**: 0 (in-package)
@@ -0,0 +1,18 @@
# Dependencies
## Internal Dependencies
```mermaid
graph TD
main --> router --> root[__root] --> TP[ThemeProvider]
root --> RL[RootLayout] --> Nav --> TT[ThemeToggle] --> TP
root --> idx[routes/index] --> LP[LandingPage] --> Sections
Sections --> content[data/content.ts]
Sections --> hook[usePackagesQuery]
classDef a fill:#63b3ed,stroke:#2b6cb0,color:#000;
class main,router,root,TP,RL,Nav,TT,idx,LP,Sections,content,hook a;
```
Text alternative: entry point leads through router and root route to ThemeProvider, layout and landing sections which use static content and the packages hook.
## External Dependencies
See `package.json` (react, @tanstack/*, @sentry/react, @fontsource/*, tailwindcss, vite, vitest). Licenses: MIT/Apache-2.0 typical; not audited here.
External service dependency: CMS/API backend for `/api/v1/offerings` (sibling repo).
@@ -0,0 +1,16 @@
# Reverse Engineering Metadata
**Analysis Date**: 2026-11-09T13:20:00Z
**Analyzer**: AI-DLC
**Workspace**: K:\Development\SlpSoftware\Projects\SlpSoftware
**Total Files Analyzed**: ~25 (key source, config and structure files)
## Artifacts Generated
- [x] business-overview.md
- [x] architecture.md
- [x] code-structure.md
- [x] api-documentation.md
- [x] component-inventory.md
- [x] technology-stack.md
- [x] dependencies.md
- [x] code-quality-assessment.md
@@ -0,0 +1,19 @@
# Technology Stack
## Programming Languages
- TypeScript 5.6 - all source
## Frameworks
- React 18.3 - UI
- TanStack Router 1.79 (hash history) - routing
- TanStack Query 5.59 - data fetching
- Tailwind CSS 3.4 - styling via CSS variables
## Infrastructure
- Gitea Actions, nginx on Raspberry Pi (reverse proxy + static web server), Sentry, Umami
## Build Tools
- Vite 5.4, pnpm, tsc -b, PostCSS/Autoprefixer
## Testing Tools
- Vitest 2.1 (jsdom), Testing Library (react, user-event, jest-dom); ESLint 9 + typescript-eslint, Prettier 3