Software Requirements Specification
Devarno Family Hub — Authentication & Admin Server
| Field | Value |
|---|---|
| Document ID | SRS-DFHUB-001 |
| Version | 1.0.0-DRAFT |
| Date | 2026-02-12 |
| Author | Devarno |
| Status | Draft — Pending Review |
1. Introduction
1.1 Purpose
This Software Requirements Specification defines the functional and non-functional requirements for the Devarno Family Hub (hereafter “the Hub”) — a centralised authentication, administration, and social platform for members of the Devarno family who hold@devarno.cloud email addresses. The Hub also serves as a cross-subdomain authentication broker, enabling seamless single sign-on (SSO) across the wider *.devarno.cloud service ecosystem.
1.2 Scope
The Hub is a Next.js (App Router, TypeScript) web application backed by BetterAuth for authentication, shadcn/ui for the component system, and Recharts for data visualisation. It is deployed as the root identity provider for alldevarno.cloud subdomains and comprises three layers:
- Identity Layer — Registration, login, session management, and cross-subdomain auth brokering.
- Profile & Social Layer — User profiles, family directory, real-time chat, and activity feeds.
- Admin Layer — User management, role-based access control, audit logging, and system health dashboards.
1.3 Definitions & Abbreviations
| Term | Definition |
|---|---|
| Hub | The Devarno Family Hub application |
| BA | BetterAuth — the TypeScript authentication framework |
| RBAC | Role-Based Access Control |
| IdP | Identity Provider — the Hub acting as OIDC provider |
| Downstream Service | Any *.devarno.cloud application consuming Hub authentication |
| Family Member | A user with a verified @devarno.cloud email |
1.4 Technology Stack (MVP)
| Layer | Technology |
|---|---|
| Framework | Next.js 15+ (App Router) |
| Language | TypeScript 5+ |
| Auth | BetterAuth (latest) + plugins |
| UI | shadcn/ui + Tailwind CSS 4 |
| Charts | Recharts |
| Database | PostgreSQL 16 |
| ORM | Drizzle ORM |
| Realtime | WebSocket (or Pusher/Ably for MVP) |
| Deployment | Docker → VPS / Coolify |
2. System Overview
2.1 Context Diagram
2.2 High-Level Architecture
3. Functional Requirements
FR-01: Email-Domain-Restricted Registration
| Attribute | Detail |
|---|---|
| ID | FR-01 |
| Priority | P0 — Must Have |
| Description | The system SHALL only allow registration for users with an @devarno.cloud email address. All other email domains SHALL be rejected at the server-side validation boundary. |
| Rationale | The Hub is a private family platform. Domain restriction is the primary access gate, ensuring only family members with provisioned email addresses can create accounts. |
| Acceptance Criteria | AC-01a: A POST to the registration endpoint with user@devarno.cloud returns 200 and creates a user record. |
AC-01b: A POST with user@gmail.com returns 403 with error message “Registration is restricted to @devarno.cloud addresses”. | |
| AC-01c: The domain check is enforced server-side (not merely client-side). | |
| Verification | Integration test against BA registration hook; manual pentest with non-family email. |
FR-02: Email & Password Authentication
| Attribute | Detail |
|---|---|
| ID | FR-02 |
| Priority | P0 — Must Have |
| Description | The system SHALL support email/password authentication as the primary sign-in method, using BetterAuth’s built-in emailAndPassword provider. Passwords SHALL be hashed with Argon2id. |
| Rationale | Email/password is the simplest auth method requiring no external dependencies. Argon2id is the OWASP-recommended password hash. BetterAuth uses this by default. |
| Acceptance Criteria | AC-02a: User can sign in with correct email + password and receives a session cookie. |
| AC-02b: Incorrect password returns 401. | |
| AC-02c: Passwords are stored as Argon2id hashes in the database (verified via DB inspection). | |
| Verification | Unit test on auth flow; DB schema inspection; automated credential-stuffing test. |
FR-03: Email Verification
| Attribute | Detail |
|---|---|
| ID | FR-03 |
| Priority | P0 — Must Have |
| Description | Upon registration, the system SHALL send a verification email to the user’s @devarno.cloud address. The user SHALL NOT be able to access protected routes until their email is verified. |
| Rationale | Confirms ownership of the email address and prevents account squatting by someone who guesses a valid family email format. |
| Acceptance Criteria | AC-03a: A new user receives a verification email within 60 seconds of registration. |
| AC-03b: Clicking the verification link marks the user as verified. | |
| AC-03c: Unverified users are redirected to a “Check your email” interstitial on any protected route. | |
| Verification | E2E test with email trap (e.g., Mailhog); manual verification flow walkthrough. |
FR-04: Session Management
| Attribute | Detail |
|---|---|
| ID | FR-04 |
| Priority | P0 — Must Have |
| Description | The system SHALL create stateful sessions using BetterAuth’s default session model. Sessions SHALL be stored in PostgreSQL and referenced via signed HTTP-only cookies. Users SHALL be able to view and revoke active sessions. |
| Rationale | Stateful sessions provide server-side revocation capability and are the BetterAuth default. Session visibility gives users control over their security. |
| Acceptance Criteria | AC-04a: On login, a better-auth.session_token cookie is set with HttpOnly, Secure, SameSite=Lax. |
| AC-04b: The user’s profile page shows all active sessions with device/IP metadata. | |
| AC-04c: Revoking a session immediately invalidates it (subsequent requests return 401). | |
| Verification | Cookie inspection in browser DevTools; session revocation integration test. |
FR-05: Cross-Subdomain Authentication Broker
| Attribute | Detail |
|---|---|
| ID | FR-05 |
| Priority | P0 — Must Have |
| Description | The system SHALL broker authentication across all *.devarno.cloud subdomains via two mechanisms: (1) cross-subdomain cookies scoped to .devarno.cloud, and (2) an OIDC Provider endpoint for downstream services that require token-based auth. |
| Rationale | The Hub is the central IdP. Cross-subdomain cookies provide frictionless SSO for browser-based subdomain apps. OIDC provides a standards-based fallback for API-centric or non-browser consumers. |
| Acceptance Criteria | AC-05a: A user logged into hub.devarno.cloud is automatically authenticated on blog.devarno.cloud without re-login. |
| AC-05b: A downstream service can exchange an authorization code for an ID token + access token via the Hub’s OIDC endpoints. | |
AC-05c: The trustedOrigins config includes https://*.devarno.cloud. | |
AC-05d: crossSubDomainCookies is enabled with domain .devarno.cloud. | |
| Verification | Multi-subdomain E2E test; OIDC conformance test against Hub endpoints. |
FR-06: User Profile Management
| Attribute | Detail |
|---|---|
| ID | FR-06 |
| Priority | P1 — Should Have |
| Description | Each authenticated user SHALL be able to view and edit their profile, including: display name, avatar (upload), bio, and timezone. The profile page SHALL be accessible at /profile. |
| Rationale | Personalisation makes the Hub feel like “home” for family members and provides identity context for chat and the family directory. |
| Acceptance Criteria | AC-06a: User can update display name and see it reflected immediately. |
| AC-06b: User can upload an avatar image (max 2MB, JPEG/PNG/WebP). | |
| AC-06c: Profile changes persist across sessions. | |
| Verification | E2E test for profile CRUD; image upload integration test. |
FR-07: Family Directory
| Attribute | Detail |
|---|---|
| ID | FR-07 |
| Priority | P1 — Should Have |
| Description | The system SHALL display a searchable directory of all registered family members showing their avatar, display name, role, and online status. |
| Rationale | Creates a sense of connectedness and allows family members to discover who else is on the platform. |
| Acceptance Criteria | AC-07a: The directory page lists all verified users. |
| AC-07b: Searching by name filters results in real-time. | |
| AC-07c: Online/offline status is accurate within 30 seconds. | |
| Verification | UI test with mock user data; presence indicator accuracy test. |
FR-08: Real-Time Family Chat
| Attribute | Detail |
|---|---|
| ID | FR-08 |
| Priority | P1 — Should Have |
| Description | The system SHALL provide a real-time chat system supporting: (a) a global family chat room, and (b) direct messages between two family members. Messages SHALL persist and be retrievable. |
| Rationale | Chat is the primary social feature driving engagement. A family-only chat room feels safe and private compared to public platforms. |
| Acceptance Criteria | AC-08a: Messages appear in the global chat within 500ms of sending. |
| AC-08b: Message history is paginated and scrollable. | |
| AC-08c: Direct messages are only visible to the two participants. | |
| AC-08d: Messages persist across page reloads and sessions. | |
| Verification | WebSocket latency test; message persistence integration test; DM access control test. |
FR-09: User Stats Dashboard
| Attribute | Detail |
|---|---|
| ID | FR-09 |
| Priority | P2 — Nice to Have |
| Description | Each user SHALL have a personal stats page rendered with Recharts, showing: login frequency (bar chart), session duration (line chart), messages sent (area chart), and profile completeness (radial). |
| Rationale | Gamification and self-awareness. Visual stats encourage engagement and give a sense of activity. Recharts is specified in the tech stack. |
| Acceptance Criteria | AC-09a: The stats page renders four chart types with real user data. |
| AC-09b: Charts are responsive and render correctly on mobile. | |
| AC-09c: Data refreshes on page load (no stale cache > 5 min). | |
| Verification | Visual regression test; data accuracy test against DB aggregates. |
FR-10: Admin — User Management
| Attribute | Detail |
|---|---|
| ID | FR-10 |
| Priority | P0 — Must Have |
| Description | Admin users SHALL be able to: list all users, view user details, ban/unban users, impersonate users, and assign roles. This SHALL use BetterAuth’s Admin plugin. |
| Rationale | Central user management is essential for a family platform admin. BetterAuth’s Admin plugin provides this out of the box with RBAC. |
| Acceptance Criteria | AC-10a: Admin can view a paginated user list at /admin/users. |
| AC-10b: Admin can ban a user, preventing them from signing in. | |
| AC-10c: Admin can impersonate a user (with audit log entry). | |
AC-10d: Non-admin users receive 403 on all /admin/* routes. | |
| Verification | RBAC integration test; impersonation audit trail verification. |
FR-11: Admin — Audit Log
| Attribute | Detail |
|---|---|
| ID | FR-11 |
| Priority | P1 — Should Have |
| Description | The system SHALL log all security-relevant events (login, logout, password change, role change, impersonation, ban) to a persistent audit table. Admins SHALL be able to view and filter the audit log. |
| Rationale | Accountability and forensic capability. Even in a family context, understanding who did what is important for trust and debugging. |
| Acceptance Criteria | AC-11a: Every login event creates an audit record with timestamp, userId, IP, and userAgent. |
| AC-11b: The admin audit log page supports filtering by event type and date range. | |
| AC-11c: Audit records are immutable (no UPDATE/DELETE permissions on the audit table). | |
| Verification | DB constraint test; audit completeness test across all event types. |
FR-12: Role-Based Access Control
| Attribute | Detail |
|---|---|
| ID | FR-12 |
| Priority | P0 — Must Have |
| Description | The system SHALL implement RBAC with at least three roles: admin, member, and child. Permissions SHALL be defined using BetterAuth’s createAccessControl and enforced on both server and client. |
| Rationale | Different family members need different access levels. Children should have restricted access. Admins need full control. |
| Acceptance Criteria | AC-12a: admin role can perform all CRUD operations on users. |
AC-12b: member role can manage their own profile and participate in chat. | |
AC-12c: child role cannot access admin routes or view audit logs. | |
| AC-12d: Role changes take effect on the next request (no stale permissions). | |
| Verification | Permission matrix test for each role × resource × action combination. |
FR-13: Password Reset Flow
| Attribute | Detail |
|---|---|
| ID | FR-13 |
| Priority | P0 — Must Have |
| Description | The system SHALL provide a “Forgot Password” flow that sends a time-limited reset link to the user’s @devarno.cloud email. The reset token SHALL expire after 1 hour. |
| Rationale | Users will forget passwords. A secure, email-based reset flow is table stakes for any auth system. |
| Acceptance Criteria | AC-13a: Requesting a reset sends an email within 60 seconds. |
| AC-13b: The reset link works exactly once and expires after 1 hour. | |
| AC-13c: After password reset, all existing sessions are revoked. | |
| Verification | Token expiry integration test; session revocation test post-reset. |
4. Non-Functional Requirements
NFR-01: Performance
| Attribute | Detail |
|---|---|
| ID | NFR-01 |
| Priority | P1 |
| Description | The Hub SHALL respond to API requests within 200ms (p95) under normal load (≤50 concurrent users). Page loads SHALL achieve a Lighthouse Performance score ≥ 90. |
| Rationale | A family hub with ~10–30 users should feel instant. BetterAuth and Next.js are both optimised for speed. |
| Acceptance Criteria | AC-NFR01a: p95 API latency < 200ms measured over 1000 requests. |
AC-NFR01b: Lighthouse Performance ≥ 90 on /, /profile, /chat. | |
| Verification | Load test with k6 or Artillery; Lighthouse CI in deployment pipeline. |
NFR-02: Security
| Attribute | Detail |
|---|---|
| ID | NFR-02 |
| Priority | P0 |
| Description | The system SHALL: (a) enforce HTTPS on all routes, (b) use CSRF protection via BetterAuth’s origin validation, (c) implement rate limiting on auth endpoints (max 10 attempts per minute per IP), (d) set all auth cookies as HttpOnly; Secure; SameSite=Lax, (e) hash passwords with Argon2id. |
| Rationale | Even a private family app must follow security best practices. BetterAuth provides most of this by default; the requirement ensures it’s configured correctly. |
| Acceptance Criteria | AC-NFR02a: HTTP requests redirect to HTTPS. |
| AC-NFR02b: 11th login attempt within 60 seconds returns 429. | |
| AC-NFR02c: Session cookies pass OWASP cookie security audit. | |
| Verification | OWASP ZAP automated scan; rate limit integration test; cookie attribute inspection. |
NFR-03: Availability
| Attribute | Detail |
|---|---|
| ID | NFR-03 |
| Priority | P2 |
| Description | The Hub SHALL target 99.5% uptime (monthly), translating to ≤ 3.6 hours of downtime per month. |
| Rationale | As the central auth broker, Hub downtime blocks access to all downstream services. 99.5% is a reasonable target for a self-hosted family service without HA clustering. |
| Acceptance Criteria | AC-NFR03a: Uptime measured by external health check ping every 60 seconds. |
| AC-NFR03b: Downtime incidents are logged with root cause. | |
| Verification | Uptime monitoring (e.g., Uptime Kuma); monthly SLA review. |
NFR-04: Scalability
| Attribute | Detail |
|---|---|
| ID | NFR-04 |
| Priority | P2 |
| Description | The system SHALL handle up to 50 concurrent authenticated users without degradation. The database schema SHALL support up to 200 registered users. |
| Rationale | Extended family + future growth. 200 users with 50 concurrent is generous for a family platform and keeps infrastructure simple. |
| Acceptance Criteria | AC-NFR04a: Load test with 50 concurrent users shows no errors and p95 < 500ms. |
| Verification | Load test with k6 simulating 50 concurrent sessions. |
NFR-05: Maintainability
| Attribute | Detail |
|---|---|
| ID | NFR-05 |
| Priority | P1 |
| Description | The codebase SHALL follow a modular architecture with clear separation between auth, profile, chat, and admin modules. TypeScript strict mode SHALL be enabled. All public functions SHALL have JSDoc comments. |
| Rationale | A solo developer with ADHD benefits from clear boundaries, type safety, and discoverable code. Strict TypeScript catches entire categories of bugs at compile time. |
| Acceptance Criteria | AC-NFR05a: tsc --noEmit passes with zero errors. |
AC-NFR05b: Each module has its own directory under src/modules/. | |
| AC-NFR05c: ESLint + Prettier pass with zero warnings. | |
| Verification | CI pipeline with type check, lint, and format gates. |
NFR-06: Accessibility
| Attribute | Detail |
|---|---|
| ID | NFR-06 |
| Priority | P1 |
| Description | The Hub SHALL conform to WCAG 2.1 Level AA for all pages. shadcn/ui components provide accessible primitives by default; custom components SHALL maintain this standard. |
| Rationale | Family members of all abilities should be able to use the Hub. shadcn/ui’s Radix UI foundation provides a strong a11y baseline. |
| Acceptance Criteria | AC-NFR06a: axe-core audit returns zero critical/serious violations. |
| AC-NFR06b: All interactive elements are keyboard-navigable. | |
| Verification | axe-core automated scan; manual keyboard navigation test. |
NFR-07: Data Privacy & Compliance
| Attribute | Detail |
|---|---|
| ID | NFR-07 |
| Priority | P1 |
| Description | The system SHALL store all user data in a self-hosted PostgreSQL instance. No user data SHALL be sent to third-party analytics or tracking services. Users SHALL be able to export their data and request account deletion. |
| Rationale | Family data is sensitive. Self-hosting ensures sovereignty. Data export and deletion are GDPR-aligned best practices even if not legally required for a private family platform. |
| Acceptance Criteria | AC-NFR07a: No third-party tracking scripts in production build. |
| AC-NFR07b: User can export their profile + chat data as JSON. | |
| AC-NFR07c: Account deletion removes all PII within 48 hours. | |
| Verification | Network traffic inspection; data export/deletion E2E test. |
5. Authentication Broker — Detailed Design
5.1 Broker Flow: Cross-Subdomain Cookies
5.2 Broker Flow: OIDC Provider (Token-Based)
5.3 BetterAuth Broker Configuration
6. Data Model
7. User Flow — Registration to First Chat Message
8. Verification Traceability Matrix
The following matrix maps each requirement to its verification method, target milestone, and responsible party.| Req ID | Requirement | Verification Method | Target Milestone | Owner |
|---|---|---|---|---|
| FR-01 | Email domain restriction | 🟢 Integration test | MVP Sprint 1 | Dev |
| FR-02 | Email/password auth | 🟢 Unit + integration test | MVP Sprint 1 | Dev |
| FR-03 | Email verification | 🟢 E2E test + 🔵 Manual | MVP Sprint 1 | Dev |
| FR-04 | Session management | 🟢 Integration test + 🟡 Cookie inspection | MVP Sprint 1 | Dev |
| FR-05 | Cross-subdomain broker | 🟢 Multi-subdomain E2E + 🔵 OIDC conformance | MVP Sprint 2 | Dev |
| FR-06 | Profile management | 🟢 E2E test | MVP Sprint 2 | Dev |
| FR-07 | Family directory | 🟢 UI test + 🔵 Manual | MVP Sprint 3 | Dev |
| FR-08 | Real-time chat | 🟢 WebSocket test + 🔵 Manual | MVP Sprint 3 | Dev |
| FR-09 | Stats dashboard | 🟢 Visual regression + 🔴 Data accuracy | MVP Sprint 4 | Dev |
| FR-10 | Admin user management | 🟢 RBAC integration test | MVP Sprint 2 | Dev |
| FR-11 | Audit log | 🟢 DB constraint test + 🟡 Completeness review | MVP Sprint 2 | Dev |
| FR-12 | RBAC | 🟢 Permission matrix test | MVP Sprint 1 | Dev |
| FR-13 | Password reset | 🟢 Token expiry test + 🟢 Session revocation test | MVP Sprint 1 | Dev |
| NFR-01 | Performance | 🟢 Load test (k6) + 🟢 Lighthouse CI | Pre-release | Dev |
| NFR-02 | Security | 🟢 OWASP ZAP + 🟡 Cookie audit | Pre-release | Dev |
| NFR-03 | Availability | 🟢 Uptime monitoring | Post-release | Ops |
| NFR-04 | Scalability | 🟢 Load test (50 concurrent) | Pre-release | Dev |
| NFR-05 | Maintainability | 🟢 CI gates (tsc, eslint, prettier) | Every PR | Dev |
| NFR-06 | Accessibility | 🟢 axe-core + 🔵 Keyboard test | Pre-release | Dev |
| NFR-07 | Data privacy | 🟡 Network inspection + 🟢 Export/delete E2E | Pre-release | Dev |
9. Requirements Summary Diagram
10. Sprint Roadmap
11. Appendix A — BetterAuth Plugin Mapping
| BetterAuth Feature/Plugin | Hub Requirement | Configuration Notes |
|---|---|---|
emailAndPassword (built-in) | FR-02, FR-13 | Enable in auth config |
admin() plugin | FR-10, FR-12 | Define custom roles: admin, member, child |
organization() plugin | FR-07 (future) | Optional for family grouping |
oidcProvider() plugin | FR-05 | Register downstream services as OIDC clients |
crossSubDomainCookies (advanced config) | FR-05 | domain: ".devarno.cloud" |
trustedOrigins (config) | FR-05, NFR-02 | "https://*.devarno.cloud" |
| Rate limiting (built-in) | NFR-02 | Default + custom stricter limits on auth routes |
| Session model (built-in) | FR-04 | Stateful sessions in PostgreSQL |
| Email verification (built-in) | FR-03 | Custom SMTP transport |
12. Appendix B — Key Decisions & Trade-offs
| Decision | Rationale | Trade-off |
|---|---|---|
| Cross-subdomain cookies as primary SSO | Frictionless UX — no redirects needed for browser apps | Only works within *.devarno.cloud; requires all services on same root domain |
| OIDC Provider as secondary SSO | Standards-based; supports non-browser and future external integrations | More complex setup; plugin is still maturing in BetterAuth |
| PostgreSQL over SQLite | Better concurrency, production-grade, supports JSON columns for audit metadata | Heavier operational footprint than SQLite |
| Stateful sessions over JWT | Server-side revocation; BetterAuth default; simpler mental model | Requires DB lookup on every request (mitigated by connection pooling) |
| shadcn/ui over custom components | Accessible by default, composable, fits Tailwind workflow | Locked into Radix UI primitives |
| Recharts over D3 | Declarative API, React-native, lower learning curve for MVP | Less flexible for highly custom visualisations |
End of SRS document.