Fuscorrespondence Requirements

Overview

Project Name: Fuscorrespondence

Short Description:

A digital messaging app designed to replicate the intentionality of communication through deliberate message delays.

Primary Goal:

Encourage thoughtful communication by reintroducing the charm and anticipation associated with traditional letter-writing.

Secondary Goals:

• Reduce the anxiety that can be associated with instant messaging
• Have a cool messaging feature users can use to communicate with me

Core Features

User Experience Improvements

Onboarding Flow

• MailboxSetupPrompt: Welcoming component that guides new users through setting up their FuscAddress
• Contextual guidance: Setup prompt appears on all main pages (mailbox, compose, drafts, sent) until mailbox is configured
• Visual consistency: Uses amber theme with MapPin icon for cohesive branding

Mobile Experience

• Animated navigation: Smooth slide-in/slide-out transitions for mobile navbar
• Touch-friendly design: Optimized for mobile interactions with proper touch targets
• Responsive layouts: All pages adapt seamlessly to different screen sizes

Visual Design

• Empty states: Meaningful empty state messages with appropriate emojis (📪 for empty mailbox)
• Content previews: Smart content truncation with line break handling for better readability
• Consistent theming: Amber color scheme throughout the app for vintage letter-writing feel

Technical UX

• Fixed scrolling: Pages only scroll when content exceeds viewport height
• Cache management: Intelligent data caching with proper invalidation strategies
• Auto-save: Draft letters save automatically every few seconds to prevent data loss

API Architecture

Current Backend Status

• Framework: Node.js + Express + TypeScript + Serverless Framework
• Deployment: AWS Lambda with API Gateway
• Database: DynamoDB monotable design
• Authentication: JWT middleware integrated with fuscauth

Implemented Endpoints

POST /mailbox - Create or update user mailbox
    GET /mailbox - Get user's mailbox information
    POST /letters - Create draft letter
    PATCH /letters/{id} - Update draft letter
    POST /letters/{id}/send - Send letter (convert draft to sent)
    GET /letters - Get user's letters (with filtering)
    GET /letters/{id} - Get specific letter
    POST /address/validate - Validate FuscAddress existence

Data Models

Letter Model (Simplified)

interface Letter {
    pk: string // LETTER#<letterId>
    senderUserId: string
    senderMailboxId: string
    recipientMailboxId: string
    status: "Draft" | "Sent" // Simplified from previous 4-state system
    isRead: boolean // Simple read tracking
    content: string
    recipientName?: string
    senderName?: string
    recipientFuscaddress?: string
    senderFuscaddress?: string
    sentDate?: string
    createdAt: string
    updatedAt: string
    }

Mailbox Model

interface Mailbox {
    pk: string // USER#<userId>
    sk: string // MAILBOX#<mailboxId>
    fuscaddress: string
    location: Location
    createdAt: string
    updatedAt: string
    }

Frontend Architecture

Technology Stack

• Framework: React 18 with TypeScript
• Build Tool: Vite
• Styling: Tailwind CSS with shadcn/ui components
• State Management: TanStack Query for server state
• Routing: React Router v6
• Authentication: JWT token management

Component Structure

src/
    ├── components/
    │   ├── ui/                    # shadcn/ui base components
    │   ├── layout/
    │   │   └── Navigation.tsx     # Main nav with mobile animations
    │   ├── letters/
    │   │   └── LetterCard.tsx     # Letter preview component
    │   └── onboarding/
    │       └── MailboxSetupPrompt.tsx  # Onboarding guidance
    ├── pages/
    │   ├── Mailbox.tsx           # Received letters view
    │   ├── Compose.tsx           # Letter writing interface
    │   ├── Drafts.tsx            # Draft management
    │   ├── SentLetters.tsx       # Sent letters tracking
    │   ├── Profile.tsx           # Mailbox setup
    │   ├── LetterReading.tsx     # Individual letter view
    │   └── NotFound.tsx          # 404 handling
    ├── hooks/
    │   └── useApi.ts             # API integration hooks
    └── lib/
    ├── api.ts                # API client
    ├── auth.ts               # Auth utilities
    ├── types.ts              # TypeScript definitions
    └── utils.ts              # Helper functions

User Flows

First-Time User Experience

1. Authentication: User logs in via fuscauth integration
2. Onboarding: MailboxSetupPrompt appears on any main page
3. Mailbox Setup: User is guided to Profile page to set up FuscAddress
4. Ready to Use: Once mailbox is configured, full app functionality is available

Letter Lifecycle

1. Compose: User writes letter in rich text editor with auto-save
2. Draft Management: Letter saved as draft, can be edited multiple times
3. Sending: User enters recipient FuscAddress with real-time validation
4. Status Tracking: Letter moves to "Sent" status, recipient can mark as read
5. Reading: Recipient views letter in mailbox, automatic read status update

Mobile Experience

1. Navigation: Animated hamburger menu with smooth slide transitions
2. Touch Interactions: All components optimized for touch input
3. Responsive Design: Layout adapts to various screen sizes seamlessly

Stretch Goals / Nice-to-Haves

• Detailed visual tracking map showing the letter's journey.
• Integration of personalized handwriting fonts.
• Spam monitoring
  • Users can report received letters to the postmaster for manual review and postmaster can ban/block the sender
• Multiple postal addresses support
  • For a more realistic letter sending experience
  • An address is associated with the user’s location
  • If a user moves location (by a significant amount, maybe cities) the app should detect the user is in a new location and setup a new postal address
  • Then the user can optionally setup mail forwarding from a postal address to another - but that incurs a delay also
    • Or they can choose to not forward mail and receive the letters sent to a postal address when they get back

User Flows

Registration & Login

1. User opens the Fuscorrespondence app
2. User is redirected to Fuscauth authentication service
3. User logs in or creates a new Fuscauth account
4. Upon successful authentication, user is redirected back to Fuscorrespondence

User Flow: Mailbox Setup

1. Access Mailbox Setup: After login, new users or users without a postal address are prompted to set up their mailbox.
2. Provide Location: User provides their current location (manually entered or via GPS).
3. Generate Postal Address:
   • System generates a unique, AI-crafted postal address associated with the user's provided location.
   • User optionally customizes or confirms the generated address.
4. Confirm Setup: User reviews and confirms mailbox setup.
5. Mailbox Ready: User mailbox setup is complete and ready to use.

User Flow: Writing a Letter

1. Navigate to Write Letter: User selects "Compose Letter" from the main menu.
2. Compose Content: User writes their letter in a minimalistic, distraction-free interface.
   • User selects basic text styling (font-size, underscore, strikethrough).
3. Save Draft: Letter is auto-saved as a draft periodically or manually by the user.
4. Review Letter: User reviews content before finalizing.

User Flow: Sending a Letter

1. Finalize Letter: User selects "Send" from the letter editing view.
2. Enter Recipient Address: User manually enters recipient’s postal address.
3. Address Validation:
   • System checks if the address entered exists.
   • If invalid, user is notified and prompted to correct.
4. Confirm Sending: User confirms sending after validation.
5. Calculate Delivery Delay: App calculates delivery time based on geographical distance between sender and recipient addresses.
6. Letter Sent: User receives confirmation the letter is now in transit.

User Flow: Viewing Received Letters

1. Check Mailbox: User opens the app and accesses their mailbox.
2. New Letter Indicator: User notices a subtle visual indicator (like a mailbox flag) signifying new letters.
3. Read Letters: User selects the new letter to open and read it.
4. Optionally Reply: User may choose to reply by composing a new letter.

User Flow: Delivery Tracking

1. Access Sent Letters: User navigates to "Sent Letters" from the main interface.
2. View Progress:
   • User selects the letter they wish to track.
   • App displays current delivery status and remaining estimated delivery time.

Stretch Goal User Flows

Reporting Spam Letters

1. Receive Suspicious Letter: User identifies a letter as spam or inappropriate.
2. Report to Postmaster:
   • User selects "Report Letter" option.
   • Letter is flagged for postmaster review.
3. Postmaster Action:
   • Postmaster reviews the flagged letter.
   • If sender is found inappropriate, they can be banned or blocked from further communication and the reporter gets a notification in app

Multiple Postal Addresses Setup

1. Detect Location Change:
   • App detects significant user location change (e.g., city change via GPS).
   • Prompt user to create a new postal address.
2. Set Up New Address:
   • User confirms or edits new postal address.
3. Mail Forwarding (Optional):
   • User chooses to set up mail forwarding from their old postal address.
   • User specifies forwarding destination and acknowledges additional delay in receiving forwarded letters.

Out of Scope

• Instant messaging.
• User profiles and other social network features - think of this as sending a letter in the 1800s
• Multimedia attachments (e.g., photos, videos, audio).
• Notifications
  • Almost added this as part of the scope but then realized that to send notifications I’d have to collect PII - don’t want to do this just yet
  • And also thought: a true letter sending experience doesn’t involve getting notified of when you get letters
  • Yes, you can see the little red flag in the mailbox when there’s something there, but you have to look at it first
  • Part of the anxiety I have from instant message apps comes from the notifications
  • So it makes sense to not include this feature
  • The premise is that the user should have the intention of knowing if they have new messages first and then use a feature that can tell them they do

Implementation Status

✅ Completed Features

Backend

• JWT authentication middleware
• Mailbox CRUD operations
• Letter drafting and sending
• Address validation system
• Status management (simplified to Draft/Sent + isRead)
• DynamoDB integration with monotable design

Frontend

• Complete UI for all core features
• Mobile-responsive design with animations
• Onboarding flow with MailboxSetupPrompt
• Auto-save functionality for drafts
• Real-time address validation
• Letter content preview system
• Cache management with TanStack Query

UX Improvements

• Fixed scrolling behavior across all pages
• Animated mobile navigation with smooth transitions
• Improved empty states with visual indicators
• Content preview optimization for better readability
• Proper error handling and loading states

🚧 Future Enhancements

Performance

• Implement delivery delay based on distance (currently simplified)
• Add background job processing for status updates
• Optimize database queries and caching strategies

Features

• Letter search and filtering
• Export/archive functionality
• Attachment support (images, documents)
• Enhanced text formatting options

Admin Features

• Spam reporting and moderation
• User management tools
• Analytics and monitoring

Technical Decisions

Simplified Status System

Decision: Moved from 4-state system (Draft → InTransit → Delivered → Read) to 2-state + boolean (Draft/Sent + isRead)

Rationale:

• Simpler to understand and implement
• Reduces complexity in UI state management
• Still provides essential tracking information
• Can be extended later if needed

Onboarding Integration

Decision: Integrated onboarding prompts directly into main pages rather than separate flow

Rationale:

• More contextual user experience
• Reduces abandonment during setup
• Allows users to see app value before committing to setup
• Easier to maintain single component vs full flow

Mobile-First Design

Decision: Prioritized mobile experience with animated navigation

Rationale:

• Most users likely to access on mobile devices
• Letter-writing on mobile creates intimate experience
• Animations enhance perceived performance and delight

Deployment Information

Backend

• URL: https://6nnj8no7u0.execute-api.us-east-1.amazonaws.com/dev/fuscorrespondence
• Environment: AWS Lambda + API Gateway
• Database: DynamoDB table fuscapp-monotable-dev

Frontend

• Technology: Vite build system
• Deployment: Static hosting (configuration dependent)
• Environment: Production-ready with optimized bundle

Last Updated: January 2025
Status: Core features implemented and functional