# JSOW Unified Portal — Design Implementation Brief

## Objective
Create the first production UI foundation for Jesus Saviour of the World, Berekum Cathedral: an Apple-inspired, mobile-first management portal shell, a complete member portal home, and a redesigned public GPS check-in experience. This is a real plain-PHP/PDO application, not a standalone mockup. Preserve existing legacy routes while adding lightweight shared presentation assets.

## Target audiences
- Church members of varied ages and technical confidence using mostly mobile phones.
- Ministry/department heads with scoped operational access.
- Finance staff, pastors, head pastor, administrators, and superadmins using one management portal.

## Existing application context
- Plain PHP 8/PDO, Apache rewrite rules, no framework or build system.
- Existing public entry is `/index.php`; admin is under `/admin/`.
- Existing logo assets include `/admin/assets/images/jsow.png` and `/admin/assets/images/jstext.png`.
- Do not depend on external CDNs, package installation, or network assets.
- Do not modify backend process files, database/config files, or legacy admin pages other than adding the new portal entry point noted below.

## Required output paths
Create these production files:
- `assets/portal/css/portal.css` — shared responsive design system.
- `assets/portal/js/portal.js` — progressive enhancement only; UI must remain usable without JS.
- `admin/portal.php` — responsive management home/app launcher. It must start a session, include `includes/config.php`, and redirect to `index` unless either `staff_user_id` or legacy `admin_username` exists. It may use safe placeholder/demo metrics until the shared backend is wired.
- `member/index.php` — member portal home. It must start a session and present a graceful signed-out state if `member_id` is absent rather than exposing data.
- `checkin.php` — redesigned public check-in page with service card, member ID/phone entry, location-readiness panel, visitor shortcut, permission/privacy guidance, and mobile bottom navigation. Its form may post to the legacy `process_check.php` for compatibility, but clearly structure hooks/data attributes for later GPS endpoint wiring.

Do not replace the existing `/index.php` yet. The lead agent will connect routes after backend verification.

## Aesthetic direction
“Apple clarity meets warm sanctuary.” Use disciplined spacing, translucent top chrome, subtle material depth, warm ivory surfaces, midnight/navy text, restrained gold accent, and gentle coral/green status colors. Avoid copying Apple branding or using generic Bootstrap dashboard patterns. No sidebar.

The memorable signature is a calm app-grid command centre: large rounded application tiles with distinctive colored icon wells, permission-aware locked/hidden states, useful live metadata, and beautiful responsive transformation into a one-handed mobile experience.

## Typography
Use a resilient local system stack: `-apple-system, BlinkMacSystemFont, "Segoe UI", Inter, Arial, sans-serif`. Strong typographic hierarchy, large readable numbers, and accessible minimum body sizes.

## Color and skins
- Light: warm off-white canvas, white/glass cards, deep ink/navy, muted slate, refined gold.
- Dark: deep midnight canvas, elevated charcoal/navy surfaces, warm white text, softened gold.
- Honor `prefers-color-scheme`, and add a persistent manual theme toggle using localStorage.
- Include high-contrast focus rings and reduced-motion support.

## Shared components
- Desktop translucent top bar with logo, portal identity, global-search visual, notifications, role chip, avatar/theme controls.
- Responsive max-width content container.
- Large page-title/hero region.
- App tile grid with inline SVG icons (simple icons only; use currentColor, accessible labels). Do not use emoji as icons.
- Status pills, metric cards, activity list, quick-action buttons, empty/error/location states.
- Desktop compact dock/quick actions, if useful.
- Mobile fixed bottom navigation with safe-area padding.
- Toast/dialog styles and skeleton/loading states that never permanently cover content.

## Management portal content
- Greeting, current role and department scope.
- At-a-glance cards: members, today attendance, visitors, departments.
- Application tiles: Members, Attendance, Departments, Finance, Services, Visitors, Children, Communication, Events, Reports, Permissions, Settings.
- Permission-driven demonstration: define a simple PHP array of available modules and filter it through a local `$visibleModules` list; lead agent will later replace this with real RBAC.
- Today’s service and check-in status.
- Recent activity/audit preview.
- Quick actions.
- No sidebar at any breakpoint.

## Member portal content
- Signed-out-safe welcome state with Member ID/phone and password inputs, plus a future OTP option.
- When `$_SESSION['member_id']` exists, show a representative authenticated shell without querying unknown columns: welcome, current service, Check In card, profile completion, attendance summary, ministries, announcements, events, digital membership card placeholder, requests/help.
- Mobile bottom navigation: Home, Check In, Events, Messages, Profile.
- Explain privacy and GPS use in friendly language.

## Public check-in content and flow
- Current service feature card with graceful “service status loading” placeholder.
- Single large phone/member-ID input and dominant Continue button.
- GPS readiness card with states: not requested, checking, ready, outside perimeter, inaccurate, denied.
- Use the browser Geolocation API only to preview permission/readiness. Do not claim client-side validation is authoritative. Populate hidden latitude, longitude, accuracy, and captured timestamp fields for later server validation.
- Visitor/first-timer entry point linking to the existing modal flow or a clear placeholder sheet.
- Accessibility: explicit labels, live status region, keyboard usability, minimum 44px controls.
- Mobile bottom navigation: Home, Check In (prominent/active), Visitor, Help.

## Icons and imagery
- Reuse the existing church logo.
- Use clean inline SVG icons for functional UI.
- Create sanctuary-inspired atmosphere with CSS gradients/geometric light shapes; no external stock imagery.
- No huge hero photo. The interface itself should carry the visual identity.

## Technical standards
- Semantic HTML5, escaped dynamic output, no raw database errors.
- No external dependencies or build step.
- Avoid inline event handlers; use `portal.js` with data attributes.
- CSS custom properties and component classes; no duplicated page-specific style blocks unless tiny and unavoidable.
- Fully responsive at 320px, 390px, 768px, 1024px, and desktop.
- Bottom nav must not obscure page content.
- Avoid permanent preloaders.
- Preserve PHP 8.0 compatibility.
- Ensure links use the application’s extensionless routing convention where appropriate.

## Boundaries
- Do not implement or fake financial transactions.
- Do not create database migrations or permission/auth backend; lead agent owns those.
- Do not modify existing legacy business logic.
- Do not expose GPS coordinates visually beyond a friendly accuracy/distance readiness message.

