Sequence Diagrams

Attribute	Value
Project	Open Projects Hub
Version	2.0
Status	Accepted

Table of Contents

• Sequence Diagrams
  • Table of Contents
  • 1) Authentication and Session Validation
  • 2) AI-Assisted Requirements Refinement
  • 3) Explicit Approval and Client Review Visibility
  • 4) Markdown Export Workflow
  • 5) Error Handling and Observability Path
  • 6) User Registration and Email Verification
  • 7) Password Reset
  • 8) Login with Rate Limiting and Lockout
  • 9) Authorization 3-Layer Defense
  • 10) Client Review by Access Code
  • 11) AI Credits Consumption and API Key Management
  • 12) AI Refinement 5-Stage Security Pipeline
  • 13) CI/CD Pipeline
  • Diagram Coverage by Feature
  • Source References

---

This document captures key user and system interaction flows for the Open Projects Hub. All diagrams reflect the current AWS-based architecture: FastAPI backend on App Runner, custom JWT auth, RDS PostgreSQL, S3 + CloudFront frontend, and S3 file storage.

1) Authentication and Session Validation

Key details: bcrypt cost factor 12; JWT signed with HS256 using env-var secret; 1-hour default expiry (configurable via JWT_EXPIRE_MINUTES). Token validation runs on every protected route.

2) AI-Assisted Requirements Refinement

3) Explicit Approval and Client Review Visibility

4) Markdown Export Workflow

5) Error Handling and Observability Path

Observability stack: Sentry Free Developer Plan (app errors, React failures, Web Vitals, route performance, release tagging) + CloudWatch Free Tier (infrastructure metrics: App Runner CPU/memory, RDS connections/storage, 5xx alarms).

---

6) User Registration and Email Verification

Shared code pattern: 6-digit alphanumeric verification codes (excl. O/0/I/1), 5-minute expiry, and 3-resend-per-15-minute rate limit are reused across registration (F-008) and password reset (F-009).

---

7) Password Reset

---

8) Login with Rate Limiting and Lockout

Counter logic: 5 failed attempts within a 15-minute sliding window triggers a 15-minute lockout. Counter resets on successful login or after the lockout period expires.

---

9) Authorization 3-Layer Defense

Defense-in-depth: Each layer acts as an independent gate. JWT validates identity, RBAC enforces the role, and every repository query is filtered by the caller's workspace, so another workspace's records read as not found. The public Client Review route sees one project's approved stories and nothing else.

---

10) Client Review by Access Code

Code security: PRJ- plus 8 characters from a 32-symbol alphabet (about 10^12 values), cryptographically random, unique across workspaces, and independent of the freelancer-chosen project code. The route is read-only, rate limited, and answers every miss identically (FR-011-04, FR-011-07, NFR-011-01, NFR-011-02; ADR-020).

---

11) AI Credits Consumption and API Key Management

Key storage: AES-256 encrypted at rest in RDS. Decrypted only at runtime during refinement. Plaintext never retrievable. No "Copy" button in UI. Post-verification hook (F-008 → F-010) grants 5 free credits on account activation.

---

12) AI Refinement 5-Stage Security Pipeline

Defense layers: 5 independent stages — no single stage is responsible for all security. Unapproved content is never stored, so it cannot reach exports, the Client Review Portal, or downstream workflows until explicitly approved by a human Admin. Rate limiting and the 5-credit trial act as additional throttling against automated abuse.

---

13) CI/CD Pipeline

Branch model: Two permanent branches (dev + main), fork-based contributions, tag-triggered production deploys. Merge to main = candidate freeze; tag vX.Y.Z = deploy to production. See the CI/CD Pipeline for full details on branching strategy, fork setup, and commit conventions.

---

Diagram Coverage by Feature

Diagram	Feature / Architecture Domain
1 — Authentication & Session Validation	F-007 (login), security-architecture.md
2 — AI-Assisted Requirements Refinement	F-002 (AI refinement), F-004 (backlog)
3 — Explicit Approval & Client Review Visibility	F-002 (approval), F-003 (access control)
4 — Markdown Export	F-004 (export)
5 — Error Handling & Observability	NFR-X01 through NFR-X06, monitoring-observability.md
6 — User Registration & Email Verification	F-008 (account creation), F-005 (onboarding trigger)
7 — Password Reset	F-009 (password reset)
8 — Login with Rate Limiting & Lockout	F-007 (admin login)
9 — Authorization 3-Layer Defense	F-003 (access control), security-architecture.md
10 — Client Review by Access Code	F-011 (client review access)
11 — AI Credits & API Key Management	F-010 (AI credits), ADR-012 (secrets management)
12 — AI Refinement 5-Stage Security Pipeline	F-002 (AI refinement), security-architecture.md
13 — CI/CD Pipeline	ci-cd-pipeline.md, deployment-architecture.md

Source References

• Architecture Solution Design
• API Contract
• Security Architecture
• CI/CD Pipeline
• Feature Requirements
• F-007: Admin Login
• F-008: Account Creation
• F-009: Reset Password
• F-010: AI Credits and API Key Management
• F-011: Client Review Access

---

Last Updated: 2026-08-11