docs(01): create phase 1 plans -- walking skeleton + portal shell

Three plans for Foundation & Portal Shell phase: - 01-01: Monorepo scaffold, Docker Compose with 3-network segmentation, NestJS API, Next.js app, PostgreSQL - 01-02: Design tokens (yellow #ffed00 primary), i18n (DE/EN), theme switching, responsive portal layout - 01-03: Visual verification checkpoint for human approval Includes SKELETON.md documenting architectural decisions for subsequent phases. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-18 09:37:08 +02:00
parent 5415d552bb
commit fc5a6f3832
5 changed files with 925 additions and 3 deletions
@@ -0,0 +1,162 @@
+---
+phase: 01-foundation-portal-shell
+plan: 03
+type: execute
+wave: 3
+depends_on:
+  - 01-02
+files_modified: []
+autonomous: false
+requirements:
+  - PRTAL-01
+  - PRTAL-04
+  - UI-01
+  - UI-02
+
+must_haves:
+  truths:
+    - "Human has verified the portal shell looks correct in browser"
+    - "Theme switching visually works (light/dark/system)"
+    - "Language switching visually works (DE/EN)"
+    - "Responsive layout adapts correctly on mobile and desktop"
+    - "Sidebar collapse/expand animates smoothly"
+---
+
+## Phase Goal
+
+**As a** user, **I want to** access a running portal application with responsive layout, theme switching, and bilingual interface, **so that** I have the structural frame into which all workflow modules will be placed.
+
+<objective>
+Visual Verification: Human confirms the portal shell meets all design decisions (D-01 through D-17) and functional requirements (PRTAL-01, PRTAL-04, UI-01, UI-02, UI-03) by interacting with the running application in a browser.
+
+Purpose: Catch visual/interaction issues that automated checks cannot detect -- color accuracy, animation smoothness, layout proportions, overall aesthetic quality.
+
+Output: Human approval or issue list for correction.
+</objective>
+
+<execution_context>
+@/home/vicolab/.claude/gsd-core/workflows/execute-plan.md
+@/home/vicolab/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/phases/01-foundation-portal-shell/01-CONTEXT.md
+@.planning/phases/01-foundation-portal-shell/01-02-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Rebuild Docker stack and verify automated checks</name>
+  <files></files>
+  <read_first>
+    docker-compose.yml (verify configuration)
+    .planning/phases/01-foundation-portal-shell/01-02-SUMMARY.md (what was built)
+  </read_first>
+  <action>
+    Run `docker compose build` to rebuild images with the latest portal shell code.
+    Run `docker compose up -d` to start all services.
+    Wait for all containers to be healthy.
+    Run automated verification: curl localhost:80 returns HTML, curl localhost:80/api/health returns JSON with status ok, pg_isready passes.
+    Run `pnpm turbo type-check` to confirm all packages type-check.
+    Run the hardcoded-string grep check: `grep -rn ">[A-Z][a-z]" apps/web/src/components/ apps/web/src/app/page.tsx --include="*.tsx"` and review any matches (filter out non-user-visible strings like className values, imports, type annotations).
+    Leave the stack running for human verification.
+  </action>
+  <verify>
+    <automated>cd /home/vicolab/projects/tessera-ctl && docker compose up -d --build 2>&1 | tail -5 && sleep 20 && curl -sf http://localhost:80 > /dev/null && echo "Web: OK" && curl -sf http://localhost:80/api/health && echo "" && echo "API: OK" && docker compose exec db pg_isready -U tessera && echo "DB: OK"</automated>
+  </verify>
+  <acceptance_criteria>
+    - All 4 containers are running (docker compose ps shows traefik, web, api, db)
+    - curl localhost:80 returns 200 with HTML content
+    - curl localhost:80/api/health returns {"status":"ok","timestamp":"..."}
+    - pg_isready exits 0
+    - pnpm turbo type-check exits 0
+  </acceptance_criteria>
+  <done>Docker stack is running and all automated checks pass, ready for human visual verification.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>
+    Complete Tessera portal shell with:
+    - Sticky header (logo left, page title center, theme toggle + locale switch + user avatar right) per D-07/D-08/D-09
+    - Collapsible left sidebar (240px expanded, ~64px collapsed icon-only) per D-01/D-02/D-04
+    - Sidebar with Dashboard + Marketplace nav items, accordion categories, footer with settings + user info per D-05/D-06/D-15
+    - Empty dashboard main content ("Keine Widgets aktiv" + add button) per D-16
+    - Yellow #ffed00 primary color, dark gray-blue dark mode per D-10/D-14
+    - Modern/clean visual style with rounded corners (~8px), subtle shadows per D-12/D-13
+    - German/English language switching via cookie per UI-02/UI-03
+    - Light/dark/system theme toggle per UI-01
+    - Responsive layout: mobile hides sidebar with hamburger per D-03/PRTAL-04
+  </what-built>
+  <how-to-verify>
+    Open http://localhost:80 in your browser and check the following:
+
+    **1. Overall Layout (D-07, D-12, PRTAL-01)**
+    - Header at top with logo "Tessera" on the left
+    - Page title / breadcrumb in center area
+    - Theme toggle, language switch, and user avatar placeholder on the right
+    - Header is sticky (scroll down if content exists -- it stays at top, D-09)
+    - Clean modern style with whitespace and subtle shadows
+
+    **2. Sidebar Behavior (D-01, D-02, D-04, D-05, D-06)**
+    - Sidebar on left side, approximately 240px wide
+    - Click the collapse/expand button -- sidebar animates to icon-only width (~64px)
+    - In expanded state: Dashboard and Marketplace labels visible with icons
+    - Dashboard entry appears active/highlighted (D-15)
+    - Categories accordion exists and can be expanded (shows "no modules" placeholder)
+    - Footer area at bottom of sidebar has settings icon and user placeholder
+    - Click collapse -- icons remain visible, labels disappear
+
+    **3. Theme Switching (UI-01, D-10, D-14)**
+    - Click theme toggle to switch to Dark mode
+    - Background changes to dark gray-blue (NOT pure black)
+    - Yellow primary color (#ffed00) remains vibrant on dark background
+    - Switch back to Light mode -- white/light background
+    - Refresh the page -- theme preference persists
+
+    **4. Language Switching (UI-02, UI-03)**
+    - Default language should be German (Deutsch)
+    - All text is in German: "Dashboard", "Marktplatz", "Einstellungen", "Keine Widgets aktiv"
+    - Click language switch to English
+    - All text changes: "Dashboard", "Marketplace", "Settings", "No active widgets"
+    - Refresh the page -- language preference persists
+
+    **5. Responsive Behavior (D-03, PRTAL-04)**
+    - Resize browser window to narrow width (< 768px)
+    - Sidebar should disappear
+    - Hamburger menu button should appear in the header
+    - Click hamburger -- sidebar slides in as overlay with backdrop
+    - Click backdrop -- sidebar closes
+    - Resize back to wide -- sidebar reappears normally
+
+    **6. Empty Dashboard (D-15, D-16)**
+    - Main content area shows "Keine Widgets aktiv" (or English equivalent)
+    - An "Add widget" button is visible (non-functional is OK for Phase 1)
+
+    **7. Color and Style (D-10, D-12, D-13)**
+    - Primary/brand color is yellow (#ffed00) visible on active states, buttons
+    - Corners are rounded (~8px radius)
+    - Overall feel: clean, modern, like Notion/Linear aesthetic
+  </how-to-verify>
+  <resume-signal>Type "approved" if the portal looks and works correctly, or describe specific issues that need fixing.</resume-signal>
+</task>
+
+</tasks>
+
+## Artifacts This Phase Produces
+
+This plan produces no new code artifacts -- it verifies the artifacts from Plans 01 and 02.
+
+<verification>
+All automated and human verification steps complete. The portal shell is confirmed visually correct and functionally working.
+</verification>
+
+<success_criteria>
+- Human has verified all 7 checklist areas
+- Human typed "approved" (or issues have been addressed)
+- Docker stack remains running and healthy
+</success_criteria>
+
+<output>
+Create `.planning/phases/01-foundation-portal-shell/01-03-SUMMARY.md` when done
+</output>