The application is structured into four primary routing surfaces under the Next.js app/ directory:
flowchart TD
AppRouter["Next.js App Router (app/)"]
AppRouter --> PublicSurface["Public Foundation Website\n• / (Home)\n• /programs & /programs/[slug]\n• /stories & /stories/[slug]\n• /impact\n• /careers\n• /contact"]
AppRouter --> LegalSurface["Legal & Metadata\n• /privacy & /terms\n• /sitemap.xml\n• /robots.txt"]
AppRouter --> AuthSurface["Identity & Auth\n• /login (Email OTP Screen)\n• /api/auth/* (Neon Auth API)"]
AppRouter --> PanelSurface["Staff Operations Panel\n• /panel (Main Dashboard)\n• /panel/posts/* (Blog Manager)\n• /panel/careers (Hiring Pipeline)\n• /panel/inquiries (Contact Triage)\n• /panel/staff (User Management)\n• /panel/audit & /panel/system"]
| Endpoint | Method | Required Role | Payload / Params | Response | Purpose & Logic |
|---|---|---|---|---|---|
/api/staff/status |
GET |
Authenticated | None | { authenticated: true, role: "ADMIN", user: {...} } |
Fetches current user session, email, role, and profile details. |
/api/staff/request-access |
POST |
Authenticated (NO_ACCESS) |
{ fullName: string, department: string } |
{ success: true, message: "Request queued" } |
Allows newly logged-in Pine Brook staff to request panel privileges. |
/api/staff/users |
GET |
ADMIN |
None | { users: [ { id, email, role, status, last_login_at } ] } |
Retrieves the list of all registered staff accounts for admin review. |
/api/staff/users |
PATCH |
ADMIN |
{ userId: number, role: "CONTENT" | "ADMIN", status: "active" | "suspended" } |
{ success: true, updatedUser: {...} } |
Updates a staff user's role or suspends their account access. |
| Endpoint | Method | Required Role | Payload / Params | Response | Purpose & Logic |
|---|---|---|---|---|---|
/api/cms/posts |
GET |
CONTENT, ADMIN |
?status=all&limit=20 |
{ posts: [...] } |
Lists all blog posts including drafts and archived articles. |
/api/cms/posts |
POST |
CONTENT, ADMIN |
{ title, slug, content, excerpt, featured_image, seo_title, seo_description } |
{ success: true, post: {...} } |
Creates a new draft article and saves initial version snapshot. |
/api/cms/posts/[id] |
PUT |
CONTENT, ADMIN |
{ title, slug, content, excerpt, status, ... } |
{ success: true, post: {...} } |
Updates post content, increments version, and creates a revision in blog_post_revisions. |
/api/cms/posts/[id]/revisions |
GET |
CONTENT, ADMIN |
None | { revisions: [ { id, revision_number, created_at, editor } ] } |
Lists full version history snapshots for the specified post. |
/api/cms/posts/[id]/restore |
POST |
CONTENT, ADMIN |
{ revisionId: number } |
{ success: true, restoredVersion: number } |
Reverts the blog post to a previously saved historical snapshot. |
| Endpoint | Method | Required Role | Payload / Params | Response | Purpose & Logic |
|---|---|---|---|---|---|
/api/careers/jobs |
GET |
Public / Staff | ?status=active |
{ jobs: [...] } |
Public fetches active vacancies; staff fetches all vacancies. |
/api/careers/jobs |
POST |
ADMIN |
{ title, department, location, employment_type, description, requirements } |
{ success: true, job: {...} } |
Creates a new job posting. |
/api/careers/applications |
GET |
CONTENT, ADMIN |
?jobId=10&status=new |
{ applications: [...] } |
Retrieves candidate job applications with linked resume metadata. |
/api/careers/applications/[id] |
PATCH |
CONTENT, ADMIN |
{ status: "interview_scheduled" | "hired" | "rejected", notes: string } |
{ success: true } |
Advances candidate through the recruitment pipeline. |
/api/resumes/[id]/download |
GET |
Staff + HMAC | ?token=HMAC_SHA256&expires=UNIX_TIMESTAMP |
Binary Stream (Content-Disposition: attachment) |
Verifies cryptographic signature and streams the candidate's CV. |
| Endpoint | Method | Required Role | Payload / Params | Response | Purpose & Logic |
|---|---|---|---|---|---|
/api/cms/settings |
GET / PUT |
ADMIN |
{ org_name, contact_email, social_links, ... } |
{ settings: {...} } |
Reads or updates global organization settings and contact info. |
/api/cms/hero-slides |
GET / POST |
CONTENT, ADMIN |
{ title, subtitle, image_url, cta_text, cta_link, display_order } |
{ slide: {...} } |
Manages homepage carousel banners. |
/api/cms/home-sections |
PUT |
CONTENT, ADMIN |
{ section_key: string, content_json: object } |
{ success: true } |
Updates modular JSONB homepage content blocks. |
/api/cms/programs |
GET / PUT |
CONTENT, ADMIN |
{ slug, title, summary, objectives, curriculum_modules } |
{ program: {...} } |
Manages program descriptions and modular curricula. |
/api/cms/faqs |
GET / POST |
CONTENT, ADMIN |
{ category, question, answer, display_order } |
{ faq: {...} } |
Manages frequently asked questions. |
/api/cms/media |
POST |
CONTENT, ADMIN |
Multipart FormData (File buffer, alt text) |
{ success: true, mediaUrl: string } |
Uploads an image asset to PostgreSQL binary/URL storage. |
| Endpoint | Method | Required Role | Payload / Params | Response | Purpose & Logic |
|---|---|---|---|---|---|
/api/cms/audit-log |
GET |
ADMIN |
?page=1&limit=50 |
{ events: [ { actor_email, action, entity_type, created_at } ] } |
Returns administrative action audit trail with PII redacted. |
/api/cms/server-logs |
GET |
ADMIN |
?level=ERROR |
{ logs: [ { level, message, metadata, created_at } ] } |
Returns recent application exceptions, 4xx/5xx frequency, and telemetry. |
/api/cms/server-logs/heartbeat |
POST |
ADMIN |
None | { status: "ok", timestamp: "..." } |
Triggers a live synthetic heartbeat check against the database and auth endpoints. |
flowchart TD
Panel["Staff Panel Dashboard (/panel)"]
Panel --> Mod1["1. Blog Manager\n• Draft, Edit, Publish\n• Versioning & Revisions\n• SEO Meta Configuration"]
Panel --> Mod2["2. Site CMS Customizer\n• Hero Slide Carousel\n• Impact Metrics & Stats\n• Programs & Curricula\n• FAQs & Office Locations"]
Panel --> Mod3["3. Media Asset Library\n• Upload & Manage Imagery\n• Alt Tag Accessibility\n• Media Asset Storage"]
Panel --> Mod4["4. Careers & Hiring\n• Post & Close Vacancies\n• Review Applications\n• HMAC Resume Downloads\n• Candidate Status Triage"]
Panel --> Mod5["5. Public Inquiries\n• Contact Form Triage\n• Newsletter Subscriber List"]
Panel --> Mod6["6. Staff & Access Control (Admin)\n• Review New Requests\n• Role Promotion / Demotion\n• Account Suspension"]
Panel --> Mod7["7. Audit Log Viewer (Admin)\n• Immutable Activity Trail\n• Filter by Actor & Action"]
Panel --> Mod8["8. Server Telemetry (Admin)\n• 4xx / 5xx Error Dashboard\n• On-Demand Health Heartbeat"]
| Platform Capability | Anonymous Public | NO_ACCESS (Pending) |
CONTENT (Editor) |
ADMIN (Administrator) |
|---|---|---|---|---|
Read published public pages (/, /programs, /stories) |
✅ | ✅ | ✅ | ✅ |
| Submit contact inquiry / newsletter signup | ✅ | ✅ | ✅ | ✅ |
| Submit job application & upload resume | ✅ | ✅ | ✅ | ✅ |
Sign in to /panel dashboard |
❌ | ✅ | ✅ | |
| Create / edit blog articles & restore revisions | ❌ | ❌ | ✅ | ✅ |
| Edit homepage sections, impact stats, & FAQs | ❌ | ❌ | ✅ | ✅ |
| Upload media assets to library | ❌ | ❌ | ✅ | ✅ |
| View job applicants & download signed resumes | ❌ | ❌ | ✅ (Full Control) | |
| Review contact inquiries & subscriber list | ❌ | ❌ | ✅ | ✅ |
Promote staff roles (CONTENT ↔ ADMIN) |
❌ | ❌ | ❌ | ✅ |
| Suspend / reactivate staff accounts | ❌ | ❌ | ❌ | ✅ |
Inspect security audit log (audit_events) |
❌ | ❌ | ❌ | ✅ |
| View server telemetry & trigger heartbeat probes | ❌ | ❌ | ❌ | ✅ |
issa/
├── app/ # Next.js App Router root
│ ├── (public)/ # Public marketing routes (Home, Programs, Stories, etc.)
│ ├── panel/ # Staff operations panel routes & dashboards
│ │ ├── posts/ # Blog CMS editor & revision viewer
│ │ ├── careers/ # Hiring pipeline & resume reviewer
│ │ ├── inquiries/ # Contact inquiries & subscriber manager
│ │ ├── staff/ # Admin staff role management
│ │ ├── audit/ # Security audit log viewer
│ │ └── system/ # Server monitoring & telemetry
│ ├── api/ # REST route handlers (/api/cms, /api/staff, etc.)
│ ├── layout.tsx # Root layout (Navigation bar, Footer, Vercel Analytics)
│ └── globals.css # Tailwind CSS base rules
├── components/ # Shared UI components
│ ├── cms/ # Reusable CMS form components and rich editors
│ ├── ui/ # Base primitives (Buttons, Modals, Badges, Tables)
│ └── layout/ # Navigation header and footer components
├── lib/ # Core backend domain services & data access
│ ├── auth/ # Neon Auth client/server wrappers and session guard
│ ├── staff.ts # Staff profile resolution, domain check, and RBAC
│ ├── cms.ts # Blog, sections, programs, and settings SQL queries
│ ├── careers.ts # Job openings, applications, and HMAC resume handling
│ ├── forms.ts # Contact submissions and newsletter subscriptions
│ ├── audit.ts # Structured audit event logger with PII redaction
│ └── server-logs.ts # Server telemetry and error recording service
├── db/ # Database definitions & schema migrations
│ └── migrations/ # Chronological SQL migrations (20260820_*.sql, etc.)
├── scripts/ # Operational and verification CLI utilities
│ ├── migrate.js # Node.js SQL migration runner
│ ├── verify-cms.js # CMS integrity verification tool
│ └── seed.js # Synthetic test data seeder for local dev
├── tests/ # Node test suite (Unit, integration, and auth contracts)
├── public/ # Static public assets (Favicon, logos, brand vectors)
├── middleware.ts # Edge middleware for session validation and route guarding
├── next.config.js # Next.js build configuration (Remote image domains, etc.)
├── package.json # Dependencies and run scripts
└── tsconfig.json # Strict TypeScript compiler options