# Dashboard, profile and administration design migration

The approved standalone design is integrated into the production React dashboard at `/dashboard`, settings at `/account`, and the super-admin views at `/dashboard?view=all` and `/dashboard?view=activity`. The standalone `frontend_prototype/` remains a separate reference.

## Structure

`documents_generator_tools_frontend/app/auth/account-pages.tsx` preserves the public page exports and dispatches personal versus ultimate-admin dashboard routes. Authentication forms remain in their own module. The ultimate-admin export delegates to the composed admin page, which shares the production workspace layout with the dashboard and profile.

`documents_generator_tools_frontend/app/workspace/` contains:

| Directory/file | Responsibility |
| --- | --- |
| `pages/` | Compose the personal dashboard, profile and admin views from shared components. |
| `components/` | Workspace layout, folder navigation, welcome/summary, project cards/library, pagination, project type chooser, dialogs, profile identity/forms, admin filters/audit entries, session controls and UI primitives. |
| `hooks/` | Project/admin queries, folders, action locking, account drafts/save feedback and sharing state. |
| `services/` | Typed calls through the existing API client, admin filters, package download and existing credential payload rules. |
| `types.ts` | Existing project, folder, sharing, capability and response contracts. |
| `i18n.ts` | New workspace copy in English/Arabic, with the existing application translator as fallback. |
| `workspace.css` | Scoped approved design styles. |
| `workspace-integration.css` | Production thumbnails, API states, navigation and compatibility with existing global CSS. |

The landing page and chooser share `app/data/project-types.ts`. Each type has a stable translation key. Only PowerPoint to SCORM is available; its link enters the existing upload flow.

## Compatibility

- Existing authentication, project UUID/editor URLs, folder/share query parameters, API routes, capabilities and request payloads are preserved.
- Folder filtering includes accessible owned/shared projects, while system tabs reset the folder filter. Folder counts come from the API. The profile sidebar links to existing folder URLs; folder management stays on the dashboard.
- Result totals describe the current query. Package and slide summaries describe the current page. No unsupported category totals are displayed.
- Shared project viewers retain personal folder moves. Edit, lifecycle, sharing, leaving and download actions follow the server capabilities; package availability and download permission are both required.
- Native dialogs handle focus, Escape, backdrop dismissal and focus return. Pending submissions block dismissal and duplicate mutations. Failed mutations retain the dialog and its draft.
- List requests abort on cleanup and reject obsolete results. Removing the last result on a page reloads a valid remaining page.
- Profile forms retain unrelated drafts across saves and language changes. Successful submissions clear only their secret fields. A blank ElevenLabs key preserves the saved key; explicit removal disables the integration. Passwords, keys and revealed link secrets are never persisted to browser storage.
- CSS selectors and animations are scoped to the workspace. The editor retains its existing design. Personal and admin pages share the sidebar, topbar, cards, chooser, dialogs and pagination. Admin cards retain owner names/emails and server capabilities, and omit personal folder moves and leave actions. Audit filters retain the existing owner, actor, action, date and search query contracts; requests reject stale responses and abort on unmount.
- The sidebar privacy and profile card styles are restored from the approved prototype. Names and workspace captions occupy separate lines; long names use ellipsis and retain their full accessible name and hover title. The desktop footer remains hidden in the existing mobile layout, where account controls remain reachable in the topbar.
- Ultimate admins switch between Personal workspace and Ultimate admin dashboard through the dropdown below the brand, available on desktop/mobile and profile pages. Personal navigation shows personal project views; admin navigation shows All projects and Activity. The switcher uses the existing `/dashboard` and `/dashboard?view=all` routes, derives its selection from the current page, and does not grant permissions or expose admin options to ordinary users. It supports arrow keys, Home/End, Escape, focus return and outside-click dismissal in English/Arabic.
- No backend source, database schema, environment, production credentials, organization activation or project files were changed.

## Checks

Run from `documents_generator_tools_frontend/`:

```powershell
npm test
npm run test:workspace
npm run lint
```

The full test command builds the production app, builds a separate React test fixture using Vite, and runs the existing Node test runner. Testing Library/jsdom are development dependencies; fixtures and generated test artifacts are excluded from production entry points. Generated artifacts live under ignored `out/`.

Verified locally on 2026-10-12:

- TypeScript check and production build passed.
- All 103 frontend tests passed, including 47 workspace cases covering personal/admin views and workspace switching.
- All new and refactored frontend modules, test helpers and build tooling passed focused ESLint with zero errors or warnings.
- Full frontend lint still reports 12 errors and 5 warnings in unchanged shared-project/editor files; baseline was 19 errors and 5 warnings. No lint rules were disabled. Generated test/build output is ignored.
- Backend account/project, folder, sharing and ultimate-admin suites passed: 23 tests, 199 assertions, using SQLite in memory.
- Existing dependency versions are unchanged. Only the focused React test dependencies were added.
- `git diff --check` passed.

For the backend checks on this Windows installation, enable SQLite for the test process because the default PHP CLI configuration does not load its drivers:

```powershell
# Run from documents_generator_tools_backend/; these variables affect this shell only.
$env:APP_ENV = 'testing'
$env:DB_CONNECTION = 'sqlite'
$env:DB_DATABASE = ':memory:'
$env:DB_URL = ''
& 'C:/laragon/bin/php/php8.3/php.exe' -d extension=php_pdo_sqlite.dll -d extension=php_sqlite3.dll vendor/bin/phpunit --filter 'AccountAndProjectTest|ProjectFolderTest|ProjectSharingTest|UltimateAdminAccessTest'
```

This command uses an ephemeral test database. Do not run database resets or migrations against the application database for this frontend change.

## Browser review still required

No supported browser automation tool is exposed in this session. jsdom checks real React interaction and dialog lifecycle; it does not verify pixel layout, native top-layer focus trapping, mobile geometry or actual browser navigation. Live-account upload/editor smoke tests were not performed.

Before deploying, compare `/dashboard` and `/account` with the prototype at desktop, tablet and phone widths (including 390px and 320px), short landscape viewports and 200% zoom, in English and Arabic/RTL:

1. Check sidebar/profile controls, summary captions, real thumbnail proportions, long names, card action contrast and the compact chooser. Small/zoomed dialogs must scroll rather than clip.
2. Navigate menus, tabs, forms and dialogs with the keyboard; confirm focus returns after close and destructive actions. Confirm the native modal traps focus.
3. Exercise search, pagination, active/shared/archive views, personal folders, accessible moves and drag/drop. Compare an owner, editor and viewer, with independent download permission and sharing enabled/disabled.
4. Open an existing project and complete the existing PowerPoint upload/preparation entry flow. Verify available packages download through the real authenticated endpoint.
5. Save profile, narration and password sections with valid and rejected data. Check that unrelated drafts survive saves/language changes, submitted secrets clear, and sign-out redirects correctly.
6. Use the workspace dropdown as a super admin to open the admin dashboard and return to the personal workspace, including from profile and mobile layouts. Check keyboard selection and dismissal. Open All projects and Activity; check that the shared sidebar marks the current page, long owner names/emails fit, owner/status/search filters and pagination work, and activity owner/actor/action/date/search filters retain their values when switching language. Check admin archive/delete dialogs, sharing, restore and permitted downloads against a live account.

No commit, push, deployment or migration is included in this delivery.