Portal
Customer-facing portal for document submission, form filling, and appointment booking. Uses separate token-based Authentication (not session-based).
Architecture
| Layer | Location |
|---|---|
| Routes | backend/src/routes/portal/ |
| Service (orchestrator) | backend/src/services/portal-service.ts |
| Sub-services | backend/src/services/portal/ — portal-access, portal-fulfillment, portal-freeform, portal-form, portal-download, portal-help, portal-notification, portal-pdf |
| Auth middleware | backend/src/middleware/portal-auth.ts |
| Appointment auth | backend/src/middleware/appointment-portal-auth.ts |
| Pages | frontend/src/pages/portal/ (+ frontend/src/pages/PortalAppointmentView.tsx) |
| Components | frontend/src/components/portal/ (27 files) |
| Queries | frontend/src/lib/queries/portalQueries.ts, portalAppointmentQueries.ts |
Portal Pages
| Page | Purpose |
|---|---|
| PortalDashboard | Customer overview with pending tasks |
| PortalFormPage | Form wizard for customer data entry |
| PortalAppointmentView | Appointment booking and management (lives at frontend/src/pages/PortalAppointmentView.tsx) |
| PortalTokenErrorPage | Token validation error handling |
Key Components
| Component | Purpose |
|---|---|
| PortalDocumentUploadModal | Upload documents for Document Obtaining |
| PortalDocumentTable / PortalDocumentCard | Display document status |
| DocumentChecklist | Track required document submission progress |
| PortalHelpChatDialog / PortalStickyChatbot | In-portal help chat |
| FormWizard/ | Multi-step form rendering (see Form Builder) |
| PortalNotificationBell | In-app Notifications |
| PortalUploadZone | Drag-and-drop file upload area |
Features
- Document upload — customers upload required Documents through a guided checklist
- Form wizard — multi-step forms created with Form Builder, rendered for customer completion
- Appointment booking — schedule and manage Appointments with renovation team
- Help chat — contextual help via sticky chatbot
- Notification bell — real-time portal Notifications
Document Upload Flow
Uploads go through portal-fulfillment-service.ts in two steps: (1) the file streams into CAS via FileService and a pending fulfillment row is created with the fileId; (2) submitFulfillments() transitions pending fulfillments to submitted and updates the collection request. Since PR#2005, each upload also enters the canonical file chain (collection → member → version, plus an opportunistic project link) introduced by PR#1752; freeform uploads run through portal-freeform-service.ts.
Authentication Flow
Portal tokens are issued per-project and sent to customers via email or SMS. The token grants scoped access to a specific project’s portal view, without requiring a full user account. For local testing, mock demo customers exist (e.g. max.mustermann@example.de / Test123!) and log in through the normal login form.
Related
- Document Obtaining — document collection workflow
- Forms — form data entities
- Form Builder — form creation system
- Appointments — appointment scheduling
- Files — uploaded file storage
- Authentication — main auth system (portal uses separate tokens)
- Notifications — multi-channel notification delivery
- Frontend Architecture — SPA structure