A remote services team needed one place for clients to complete onboarding, see project status, and retrieve documents—without turning Slack into the system of record.
Next.jsTailwind CSSPrismaPostgreSQLAuth.js
Client challenge
Status lived in threads. Documents lived in shared drives with unclear versions. New clients asked the same onboarding questions repeatedly. Support staff spent hours answering ‘where are we?’ instead of doing delivery work.
Constraints
• Clients had varying technical comfort—UI had to stay plain
• Existing auth provider had to be reused
• No dedicated mobile app in phase one
• Content owners needed to update help text without deploys
Engineering decisions
Dashboard-first information architecture
Every role lands on a single overview: outstanding tasks, recent updates, and documents needing attention. Deep links exist, but the home state answers the first question.
Role-aware navigation
Client, delivery lead, and admin see different nav density. We avoided a mega-menu that exposed internal tools to clients.
Document checkpoints instead of freeform uploads
Required documents are checklist items with states (missing, submitted, approved). That gave ops a queue instead of a folder full of mystery PDFs.
Architecture
Next.js App Router with authenticated route group. Prisma models for projects, memberships, documents, and activity events. Auth.js sessions gate every portal route. File metadata lives in Postgres; binaries in object storage referenced by signed URLs.
Implementation
We shipped the portal shell, membership invites, document checklist, and activity feed first. Email notifications fire on state changes that require client action. Editors update onboarding copy through a structured content path so engineering is not on the critical path for wording tweaks.
Tradeoffs
• Deferred real-time chat—activity feed + email covered the first release
• Accepted a simpler notification model rather than a full preference center
• Kept PDF preview basic; rich annotation waits for phase two
Lessons learned
• Clients care more about ‘what do you need from me?’ than about vanity dashboards
• Document states beat folders for operational clarity
• Role-aware nav prevents accidental exposure of internal tooling
Outcome
Onboarding became a checklist instead of a scavenger hunt. Status questions dropped because the portal showed the same truth the team used internally. Document handoff gained a reviewable trail.
Future improvements
Phase two candidates: finer notification preferences, richer file preview, and optional client-side commenting on documents.
