Authentication Flow

sequenceDiagram participant User participant App participant Cognito participant SES as Email (SES) participant API participant DDB as DynamoDB User->>App: Enter email, password, name App->>Cognito: SignUp Cognito->>SES: Send verification code SES-->>User: Email with code Cognito-->>App: User created (unconfirmed) User->>App: Enter verification code App->>Cognito: ConfirmSignUp Cognito-->>App: User confirmed App->>Cognito: InitiateAuth Cognito-->>App: Tokens (ID, Access, Refresh) App->>API: POST /users (with ID token) API->>API: Validate token API->>DDB: Create user profile DDB-->>API: Profile created API-->>App: User profile App-->>User: Welcome! Start onboarding

sequenceDiagram participant User participant App participant Cognito participant API User->>App: Enter email, password App->>Cognito: InitiateAuth (USER_SRP_AUTH) alt Valid Credentials Cognito-->>App: Tokens (ID, Access, Refresh) App->>App: Store tokens securely App->>API: GET /users/me API->>API: Validate ID token API-->>App: User profile App-->>User: Dashboard else MFA Required Cognito-->>App: Challenge: SMS_MFA App-->>User: Enter MFA code User->>App: MFA code App->>Cognito: RespondToAuthChallenge Cognito-->>App: Tokens else Invalid Credentials Cognito-->>App: NotAuthorizedException App-->>User: Invalid email or password end

sequenceDiagram participant App participant TokenService as Token Service participant Cognito participant API App->>TokenService: Make API request TokenService->>TokenService: Check access token expiry alt Token Valid TokenService->>API: Request with access token API-->>App: Response else Token Expired TokenService->>Cognito: InitiateAuth (REFRESH_TOKEN) alt Refresh Successful Cognito-->>TokenService: New tokens TokenService->>TokenService: Store new tokens TokenService->>API: Request with new access token API-->>App: Response else Refresh Token Expired Cognito-->>TokenService: NotAuthorizedException TokenService-->>App: Redirect to login end end

flowchart TB subgraph Roles["User Roles"] Admin["Family Admin\n- Full control\n- Invite members\n- Remove members\n- Manage settings"] Member["Family Member\n- View content\n- Create content\n- Vouch for others"] Viewer["Viewer (Future)\n- View only\n- No create\n- No vouch"] end subgraph Permissions["Permissions"] P1["view:content"] P2["create:content"] P3["delete:content"] P4["invite:member"] P5["remove:member"] P6["vouch:member"] P7["manage:family"] end Admin --> P1 & P2 & P3 & P4 & P5 & P6 & P7 Member --> P1 & P2 & P6 Viewer --> P1

sequenceDiagram participant App participant APIG as API Gateway participant Authorizer as Cognito Authorizer participant Lambda participant DDB as DynamoDB App->>APIG: GET /families/{id}/content Note right of App: Authorization: Bearer APIG->>Authorizer: Validate token Authorizer->>Authorizer: Verify JWT signature Authorizer->>Authorizer: Check expiration Authorizer->>Authorizer: Extract claims alt Valid Token Authorizer-->>APIG: Allow + claims APIG->>Lambda: Forward request + claims Lambda->>Lambda: Extract userId from claims Lambda->>DDB: Check family membership alt User is member DDB-->>Lambda: Membership record Lambda->>DDB: Fetch content DDB-->>Lambda: Content Lambda-->>APIG: 200 OK + content APIG-->>App: Content else Not a member DDB-->>Lambda: No membership Lambda-->>APIG: 403 Forbidden APIG-->>App: Access denied end else Invalid Token Authorizer-->>APIG: Deny APIG-->>App: 401 Unauthorized end