Benell/dev_plan_1.md

<!--  --># Casa Benell - Dev Plan 1

## Goal
Stabilize UI quality (responsive + proportional typography), adopt final brand assets, and start backend foundations for users/roles/invitations with PostgreSQL and SMTP.

## Current pain points (from first pass)
- Typography scale is too large in several views.
- Numeric values overflow cards and break layout.
- Desktop-first layout is not fully adaptive on mobile.
- Sidebar needs a true mobile hamburger/sheet pattern.
- Brand assets in use are placeholders, not final logo/character files.
- No DB/auth/invite flow yet (all role switching is local UI state).

## Inputs confirmed
- Final logo source: `/home/mdares03/benell/example_ui_img/benell_logo.webp`
- Theme character source: `/home/mdares03/benell/example_ui_img/Logo Benito.png`

## Implementation strategy (phased)

### Phase 1 - Responsive UI hardening
Scope:
- Normalize type scale and spacing so content always fits card boundaries.
- Prevent number overflow in KPI cards, tables, and right panels.
- Add mobile nav with hamburger + slide-out menu.
- Improve responsive behavior for top bar filters/search/role selector.

Tasks:
1. Define responsive typography tokens with `clamp(...)` and semantic utility classes.
2. Replace oversized heading/body classes with tokenized scale:
   - H1/H2/H3/body/label/caption.
3. Apply overflow-safe text rules:
   - `min-w-0` in flex/grid children.
   - `truncate`/`break-words` where needed.
   - `tabular-nums` for KPI numeric alignment.
4. Refactor cards/tables to use adaptive grids:
   - desktop: 4 columns where available
   - tablet: 2 columns
   - mobile: 1 column
5. Build mobile sidebar pattern:
   - top-left hamburger button
   - drawer/sheet navigation
   - keyboard and focus support
6. Make Sankey containers responsive with controlled heights by breakpoint.
7. Validate at widths: 360, 390, 768, 1024, 1280, 1536.

Acceptance criteria:
- No text or numbers overflow containers at target breakpoints.
- Dashboard, Financial Flow, Meetings, People remain usable on mobile.
- Navigation works via sidebar (desktop) and hamburger drawer (mobile).

---

### Phase 2 - Final brand asset integration
Scope:
- Replace placeholder brand files with provided official assets.

Tasks:
1. Copy and normalize assets into `/public/brand/`:
   - `logo.webp` from `benell_logo.webp`
   - `mascot.png` from `Logo Benito.png`
2. Update components to use final files in:
   - sidebar/header brand block
   - login page
   - empty states
3. Verify object-fit/crop so assets render clean on desktop + mobile.

Acceptance criteria:
- Only final brand assets are used in app shell and empty states.
- No stretching, clipping, or quality loss in common viewport sizes.

---

### Phase 3 - PostgreSQL foundation + RBAC data model
Scope:
- Start real user data layer with psql.
- Keep mock business metrics for now, but migrate auth/user/role from local store to DB-backed model.

Tech decisions (proposed):
- ORM: Prisma
- DB: PostgreSQL
- Auth/session: NextAuth/Auth.js with DB adapter
- Password hashing: bcrypt
- Email: Nodemailer SMTP transport

Core schema (initial):
1. `users`
   - `id`, `name`, `email` (unique), `password_hash`, `status`, `created_at`, `updated_at`
2. `roles`
   - `id`, `key` (`owner|leader|employee`), `name`
3. `user_roles`
   - `user_id`, `role_id` (many-to-many)
4. `invitations`
   - `id`, `email`, `role_key`, `token_hash`, `expires_at`, `accepted_at`, `invited_by`, `created_at`
5. `user_locations` (optional in this phase, recommended)
   - `user_id`, `location_id`

Tasks:
1. Add Prisma and configure `DATABASE_URL`.
2. Create schema + first migration.
3. Add seed script for default roles and bootstrap owner account.
4. Add auth route handlers and session callback to include role.
5. Add middleware route protection for authenticated app routes.
6. Replace UI-only role switcher with role from session (keep optional dev override flag).

Acceptance criteria:
- App can connect to PostgreSQL locally.
- At least one owner user can login from DB.
- Protected routes reject anonymous requests.
- Role can be read from DB session payload.

---

### Phase 4 - Invitation flow via SMTP
Scope:
- Admin/owner can invite users by email and assign role.

Tasks:
1. Add env variables for SMTP and app URLs.
2. Create server actions or API routes:
   - `POST /api/invitations`
   - `POST /api/invitations/accept`
3. Generate secure random invitation tokens; store hash only.
4. Send email with invitation link (token + expiry).
5. Create acceptance page:
   - set password
   - confirm profile basics
   - finalize user + role assignment
6. Add invitation status UI in admin/settings page.

Acceptance criteria:
- Owner can send invite with selected role.
- Recipient can accept invite and create account before expiry.
- Used/expired tokens are rejected.

---

### Phase 5 - Operational readiness and migration cleanup
Scope:
- Make deployment process stable under existing systemd flow.

Tasks:
1. Add `.env.example` with required vars only (no secrets).
2. Add startup checks for missing env values.
3. Document production sequence:
   - `npm run build`
   - `sudo systemctl restart benell.service`
4. Add backup/rollback notes for DB migrations.

Acceptance criteria:
- Clear runbook for local/prod env setup.
- No manual guessing for env keys or migration order.

## Environment variables to add (planned)
- `DATABASE_URL=postgresql://...`
- `NEXTAUTH_URL=https://benell.maliountech.com.mx`
- `NEXTAUTH_SECRET=...`
- `SMTP_HOST=...`
- `SMTP_PORT=587`
- `SMTP_USER=...`
- `SMTP_PASS=...`
- `SMTP_FROM="Casa Benell <noreply@...>"`
- `INVITE_TTL_HOURS=72`

## Risks and mitigations
- Risk: auth migration blocks UI progress.
  - Mitigation: complete UI responsive fixes first, then backend integration.
- Risk: role logic duplicated in client and server.
  - Mitigation: single source of truth from session role, with temporary dev override only.
- Risk: invite token leakage.
  - Mitigation: store hashed tokens, set short expiry, single-use tokens.

## Execution order
1. Phase 1 (UI hardening)
2. Phase 2 (brand assets)
3. Phase 3 (DB + auth + RBAC)
4. Phase 4 (SMTP invites)
5. Phase 5 (runbook + stability)

## Deliverables for this plan
- Responsive and proportional UI baseline.
- Mobile hamburger navigation.
- Final branding applied.
- PostgreSQL user/role foundation.
- SMTP invitation workflow.
- Updated docs for env and deployment.