Skip to content

PetFolio wire-framing

This page documents the wire-framing process for PetFolio, covering design decisions, technical choices, and user flows for both personal and business accounts.

Design decisions

Key assumptions

  • Modern browser support (CSS3, Flexbox)
  • Mobile-first responsive approach
  • Semantic HTML for accessibility
  • Will integrate with external identity provider

Design inspiration

  • Subdomain approach: Slack, Shopify, Zendesk
  • Clean login UX: Notion, Linear, Figma
  • Business SSO: Google Workspace, Microsoft 365

Visual design philosophy

  • Low-fidelity wireframes: Focus on structure and layout, not aesthetics
  • Placeholder elements: Logo, icons, and imagery represented as boxes with labels
  • Minimal styling: Basic borders, spacing, and typography only
  • Non-functional: Static HTML, no backend integration or validation

Layout / responsiveness

Breakpoints:

1
2
3
4
5
xs (extra-small):  0px - 599px
sm (small):        600px - 899px
md (medium):       900px - 1199px
lg (large):        1200px - 1535px
xl (extra-large):  1536px+

User experience priorities

Personal Users:

  • Casual, welcoming tone
  • Multiple convenient login options
  • Clear path to account creation
  • Simple, friendly language

Business Users:

  • Professional tone and presentation
  • Business-focused authentication methods
  • Clear account context (subdomain display)
  • Admin support options
  • Sales-oriented CTA ("Request Demo / Sign Up")

Technical decisions

Account architecture

Decision: Separate Domains for Account Types

  • Personal Accounts: petfolio.com or app.petfolio.com
  • Business Accounts: Subdomain per business (e.g., thepositivepup.petfolio.com)

Rationale:

  • Eliminates need for account type selection during login
  • Better branding for business clients
  • Easier bookmarking and navigation
  • Enhanced security through account isolation
  • Follows B2B SaaS industry standard (Slack, Shopify, etc.)

Alternative Rejected: Account name/ID field (like AWS Console)

  • Adds friction to login flow
  • Requires users to remember account identifier
  • Potential for typos and confusion

Questions answered during design

Q: Should businesses have an account name field like AWS?

A: No, use subdomains instead (e.g., thepositivepup.petfolio.com)

  • Better UX, security, and branding
  • Industry standard for B2B SaaS
Q: Will email/password be secure if using OAuth?

A: Yes, identity provider (like Keycloak) handles password security

  • PetFolio never stores passwords
  • Can offer both OAuth social login AND email/password safely
Q: Should business accounts have Facebook login?

A: No, not typical for business use

  • Focus on Google Workspace and Microsoft 365
  • Better alignment with business workflows
Q: Same login page for personal and business?

A: No, separate pages accessed via different domains

  • Different branding, messaging, and auth options
  • Clear context for user about which system they're accessing
Q: Should business sign-up include OAuth (Google/Microsoft)?

A: No, not for MVP - only email/password

  • OAuth "Sign up with Google/Microsoft" creates confusion (users think it's enterprise SSO)
  • OAuth only creates one admin user - doesn't connect to organization directory
  • Still need to manually invite all team members
  • Enterprise SSO is a future feature (see below)

Future: Enterprise SSO vs OAuth

  • OAuth (Individual): "Continue with Google" - authenticates one person
  • Enterprise SSO: Connects to Google Workspace/Microsoft 365 organization directory
  • Admin configures SSO in settings, can auto-provision or control access
  • Requires SAML/OIDC integration with organization's identity provider

Not yet addressed (future work)

Business account verification (future)

Approach: Automated Self-Service with Optional Verification

For initial launch, all business types can self-register without verification. Future iterations will add:

  • Breeder License Verification (Priority for ethical compliance)
    • Upload business license/certification during or after signup
    • Admin review workflow for approving uploaded documents
    • Account status: Basic (unverified) vs Verified
    • Feature gating: Premium features locked until verified
    • Dashboard banner: "Complete verification to unlock all features"
  • Subdomain Conflict Prevention
    • Real-time subdomain availability check (already in wireframe)
    • Suggestions when subdomain is taken
    • Validation before form submission
  • Sales-Led Onboarding (Optional path for enterprise clients)
    • Request demo flow for multi-location businesses
    • Manual provisioning by PetFolio team
    • Not needed for MVP - all businesses use self-service

Authentication features

  • Multi-factor authentication (MFA)
  • Session management and timeout behaviour
  • Password strength requirements and validation
  • Error states and validation messaging
  • Loading states during authentication
  • "Remember me" / stay logged in functionality
  • Account lockout policies
  • Rate limiting for login attempts

User flows

  • ✅ Sign-up/registration flow (business accounts - basic)
  • ✅ Email verification process (business accounts)
  • ✅ Password reset flow (business accounts - simplified)
  • Sign-up/registration flow (personal accounts)
  • Email verification process (personal accounts)
  • Password reset flow (personal accounts)
  • First-time user onboarding
  • Terms of service and privacy policy acknowledgment

Additional pages needed

  • Dashboard/home page (personal account)
  • ✅ Dashboard/home page (business account - basic with navigation)
  • Account selection (if user has multiple business accounts)
  • Profile settings
  • Pet profile management
  • Appointment scheduling
  • Communication/messaging interface

Business-specific features

  • Team member invitation and management
  • Role-based access control (RBAC)
  • Business settings and preferences
  • Integration management (calendars, payment systems, etc.)
  • Client/pet access requests and permissions

Enterprise SSO (future feature)

Planned Approach for Post-MVP:

Businesses will be able to configure enterprise SSO to connect PetFolio with their organization's identity provider:

Supported Providers:

  • Google Workspace (SAML/OIDC)
  • Microsoft 365/Azure AD (SAML/OIDC)
  • Okta, Auth0, OneLogin (SAML/OIDC)

Configuration Flow:

graph TD
    A[Admin Dashboard] --> B[Settings → SSO Configuration]
    B --> C{Select Provider}
    C -->|Google Workspace| D[Enter Workspace Domain]
    C -->|Microsoft 365| E[Enter Tenant ID]
    C -->|Other SAML| F[Upload Metadata XML]

    D --> G[Test Connection]
    E --> G
    F --> G

    G --> H{Test Successful?}
    H -->|Yes| I[Enable SSO]
    H -->|No| J[Show Error & Troubleshoot]

    I --> K[Choose Provisioning Mode]
    K --> L[Auto-provision all users<br/>from directory]
    K --> M[Manual invitation only<br/>SSO for login]

    classDef layer-domain fill:#7ed32126,stroke:#7ed321,stroke-width:2px
    classDef neutral fill:#c8c8c826,stroke:#999999,stroke-width:1.5px

    class A,G,I layer-domain
    class B,C,D,E,F,H,J,K,L,M neutral

User Management Options:

  1. Auto-provisioning: Sync all users from org directory → Automatic account creation
  2. Manual + SSO Login: Admin invites users → Users log in via SSO (no password needed)
  3. Hybrid: Combine both approaches with role mapping

Benefits:

  • No password management for team members
  • Centralised access control through org's IdP
  • Automatic offboarding when user removed from org
  • Single sign-on experience across all business tools

Database Schema Additions:

  • SSO configuration per business account
  • User identity mapping (SSO ID → PetFolio User)
  • Authentication method per user (email/password, SSO, OAuth)