tessera-ctl/.planning/phases/01-foundation-portal-shell/01-03-PLAN.md

---
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>