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:
@@ -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
|
||||
Reference in New Issue
Block a user