notes/projects/network-app/blueprint.md

The Network App - Project Blueprint

Date: 2025-06-26
Version: 1.0
Purpose: Technical architecture, screens, data models, and development plan

---

1. App Architecture Diagram

┌────────────────────────────────────────────────────────────────────┐
│                         iOS APPLICATION                             │
├────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                     PRESENTATION LAYER                        │  │
│  │                                                               │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │  │
│  │  │Dashboard│ │ Clients │ │ Matches │ │Messages │ │Settings│ │  │
│  │  │  View   │ │  View   │ │  View   │ │  View   │ │  View  │ │  │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬───┘ │  │
│  │       │           │           │           │           │      │  │
│  │  ┌────▼───────────▼───────────▼───────────▼───────────▼───┐ │  │
│  │  │                    VIEW MODELS                          │ │  │
│  │  │  DashboardVM │ ClientsVM │ MatchesVM │ CommsVM │ SettingsVM│  │
│  │  └─────────────────────────┬──────────────────────────────┘ │  │
│  └────────────────────────────│───────────────────────────────┘  │
│                               │                                   │
│  ┌────────────────────────────▼───────────────────────────────┐  │
│  │                      DOMAIN LAYER                           │  │
│  │                                                              │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │  │
│  │  │  Use Cases  │ │   Models    │ │ Repository  │           │  │
│  │  │             │ │             │ │  Protocols  │           │  │
│  │  │ - GetClients│ │ - Client    │ │             │           │  │
│  │  │ - SaveClient│ │ - Match     │ │ - ClientRepo│           │  │
│  │  │ - GenEmail  │ │ - Message   │ │ - MatchRepo │           │  │
│  │  │ - FindMatch │ │ - Event     │ │ - AIService │           │  │
│  │  └─────────────┘ └─────────────┘ └─────────────┘           │  │
│  └─────────────────────────────┬────────────────────────────────┘  │
│                                │                                   │
│  ┌─────────────────────────────▼────────────────────────────────┐  │
│  │                       DATA LAYER                              │  │
│  │                                                               │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │  │
│  │  │  Firebase   │  │   Claude    │  │    Local    │          │  │
│  │  │  Service    │  │   Service   │  │    Cache    │          │  │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │  │
│  └─────────│────────────────│────────────────│──────────────────┘  │
└────────────│────────────────│────────────────│──────────────────────┘
             │                │                │
             ▼                ▼                ▼
┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│   FIRESTORE    │  │ CLOUD FUNCTION │  │   CORE DATA    │
│   DATABASE     │  │  (AI PROXY)    │  │   (OFFLINE)    │
└────────────────┘  └───────┬────────┘  └────────────────┘
                            │
                            ▼
                   ┌────────────────┐
                   │   CLAUDE API   │
                   │   (ANTHROPIC)  │
                   └────────────────┘

---

2. Key Screens & Wireframes

2.1 Dashboard (Home)

┌─────────────────────────────────────┐
│ ◀ The Network App          👤 ⚙️    │
├─────────────────────────────────────┤
│                                     │
│  Good morning, David                │
│                                     │
│  ┌─────────────────────────────┐   │
│  │  🎂 UPCOMING THIS WEEK       │   │
│  │                              │   │
│  │  Today   John Smith (60th)   │   │
│  │  Wed     Mary Johnson Anniv  │   │
│  │  Fri     Follow-up: Bob Lee  │   │
│  │                              │   │
│  │  [View All Events]           │   │
│  └─────────────────────────────┘   │
│                                     │
│  ┌─────────────────────────────┐   │
│  │  🤝 SUGGESTED CONNECTIONS    │   │
│  │                              │   │
│  │  ┌────┐  ┌────┐              │   │
│  │  │ JS │──│ TW │  Both golf   │   │
│  │  └────┘  └────┘  enthusiasts │   │
│  │                              │   │
│  │  [Review Match]              │   │
│  └─────────────────────────────┘   │
│                                     │
│  ┌─────────────────────────────┐   │
│  │  📝 DRAFT MESSAGES (3)       │   │
│  │                              │   │
│  │  Birthday wish for John...   │   │
│  │  Newsletter intro for...     │   │
│  │                              │   │
│  └─────────────────────────────┘   │
│                                     │
├─────────────────────────────────────┤
│  🏠      👥      🤝      ✉️      ⚙️  │
│  Home  Clients Matches Messages Set │
└─────────────────────────────────────┘

2.2 Client List

┌─────────────────────────────────────┐
│ ◀ Clients                    ➕ 🔍  │
├─────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ 🔍 Search clients...            │ │
│ └─────────────────────────────────┘ │
│                                     │
│ [All] [VIP] [Recent] [Birthdays]   │
│                                     │
│ ┌─────────────────────────────────┐ │
│ │ 👤 John Smith              🎂 ▶ │ │
│ │    CEO, Smith Ventures          │ │
│ │    Last contact: 2 days ago     │ │
│ └─────────────────────────────────┘ │
│                                     │
│ ┌─────────────────────────────────┐ │
│ │ 👤 Mary Johnson               ▶ │ │
│ │    Retired, Real Estate         │ │
│ │    Last contact: 1 week ago     │ │
│ └─────────────────────────────────┘ │
│                                     │
│ ┌─────────────────────────────────┐ │
│ │ 👤 Robert Lee             🔔 ▶  │ │
│ │    Attorney, Lee & Partners     │ │
│ │    Follow-up due                │ │
│ └─────────────────────────────────┘ │
│                                     │
│           ... more clients ...      │
│                                     │
├─────────────────────────────────────┤
│  🏠      👥      🤝      ✉️      ⚙️  │
└─────────────────────────────────────┘

2.3 Client Profile

┌─────────────────────────────────────┐
│ ◀ Back                    ✏️  •••   │
├─────────────────────────────────────┤
│                                     │
│         ┌───────────┐              │
│         │    👤     │              │
│         │   Photo   │              │
│         └───────────┘              │
│         John Smith                  │
│         CEO, Smith Ventures         │
│                                     │
│  📞 (555) 123-4567   ✉️ Email       │
│                                     │
├─────────────────────────────────────┤
│ [Overview] [Notes] [History] [AI]   │
├─────────────────────────────────────┤
│                                     │
│  📅 IMPORTANT DATES                 │
│  Birthday: March 15 (turns 60)      │
│  Client since: 2018 (7 years)       │
│  Anniversary: June 22               │
│                                     │
│  💼 PROFESSIONAL                    │
│  CEO at Smith Ventures              │
│  Industry: Private Equity           │
│  Previously: Goldman Sachs          │
│                                     │
│  ❤️ INTERESTS                       │
│  Golf • Wine collecting • Jazz      │
│  Stanford alumni • Board member     │
│                                     │
│  👨‍👩‍👧‍👦 FAMILY                        │
│  Spouse: Sarah                      │
│  Kids: Emma (28), Michael (25)      │
│                                     │
│  🏷️ TAGS                            │
│  [VIP] [Referral Source] [Golf]     │
│                                     │
├─────────────────────────────────────┤
│  [📧 Generate Email] [🤝 Find Match]│
└─────────────────────────────────────┘

2.4 AI Message Generation

┌─────────────────────────────────────┐
│ ◀ Generate Message                  │
├─────────────────────────────────────┤
│                                     │
│  To: John Smith                     │
│                                     │
│  Purpose:                           │
│  ┌─────────────────────────────┐   │
│  │ ● Birthday Wish              │   │
│  │ ○ Check-in                   │   │
│  │ ○ Meeting Follow-up          │   │
│  │ ○ Introduction               │   │
│  │ ○ Custom                     │   │
│  └─────────────────────────────┘   │
│                                     │
│  Additional context (optional):     │
│  ┌─────────────────────────────┐   │
│  │ Mention the wine we          │   │
│  │ discussed last month...      │   │
│  └─────────────────────────────┘   │
│                                     │
│  [✨ Generate with AI]              │
│                                     │
├─────────────────────────────────────┤
│  AI GENERATED DRAFT                 │
│  ┌─────────────────────────────┐   │
│  │ Dear John,                   │   │
│  │                              │   │
│  │ Happy 60th birthday! I hope │   │
│  │ you're celebrating with     │   │
│  │ Sarah and that bottle of    │   │
│  │ '82 Margaux we talked       │   │
│  │ about at the club...        │   │
│  │                              │   │
│  │ [Edit]                       │   │
│  └─────────────────────────────┘   │
│                                     │
│  [🔄 Regenerate] [✅ Approve & Send]│
│                                     │
└─────────────────────────────────────┘

2.5 Match Suggestions

┌─────────────────────────────────────┐
│ ◀ Network Matches           🔄      │
├─────────────────────────────────────┤
│                                     │
│  AI-suggested connections between   │
│  your clients who may benefit from  │
│  knowing each other.                │
│                                     │
│ ┌─────────────────────────────────┐ │
│ │  ┌────┐          ┌────┐        │ │
│ │  │ JS │──────────│ TW │        │ │
│ │  └────┘          └────┘        │ │
│ │  John Smith    Tom Wilson      │ │
│ │                                 │ │
│ │  MATCH SCORE: 87%              │ │
│ │                                 │ │
│ │  🎯 Why they'd connect:        │ │
│ │  • Both avid golfers (single   │ │
│ │    digit handicaps)            │ │
│ │  • Both Stanford MBA alumni    │ │
│ │  • John looking for PE deals;  │ │
│ │    Tom has portfolio co exits  │ │
│ │                                 │ │
│ │  [❌ Not a Fit]  [✅ Introduce] │ │
│ └─────────────────────────────────┘ │
│                                     │
│ ┌─────────────────────────────────┐ │
│ │  ┌────┐          ┌────┐        │ │
│ │  │ MJ │──────────│ SL │        │ │
│ │  └────┘          └────┘        │ │
│ │  Mary Johnson   Susan Lee      │ │
│ │                                 │ │
│ │  MATCH SCORE: 72%              │ │
│ │  ...                           │ │
│ └─────────────────────────────────┘ │
│                                     │
├─────────────────────────────────────┤
│  🏠      👥      🤝      ✉️      ⚙️  │
└─────────────────────────────────────┘

---

3. Data Models

3.1 Swift Models

// MARK: - Client Model

struct Client: Identifiable, Codable {
    let id: String
    var userId: String
    
    // Basic Info
    var firstName: String
    var lastName: String
    var email: String?
    var phone: String?
    var address: Address?
    var photoURL: String?
    
    // Professional
    var company: String?
    var role: String?
    var industry: String?
    var previousCompanies: [String]?
    
    // Personal
    var birthday: Date?
    var anniversary: Date?
    var interests: [String]
    var family: FamilyInfo?
    var preferences: [String: String]
    
    // Metadata
    var tags: [String]
    var notes: [Note]
    var clientSince: Date
    var lastContactedAt: Date?
    var matchPreferences: MatchPreferences
    
    var createdAt: Date
    var updatedAt: Date
    
    var fullName: String {
        "\(firstName) \(lastName)"
    }
}

struct Address: Codable {
    var street: String?
    var city: String?
    var state: String?
    var zip: String?
    var country: String?
}

struct FamilyInfo: Codable {
    var spouseName: String?
    var children: [FamilyMember]?
}

struct FamilyMember: Codable {
    var name: String
    var age: Int?
    var relationship: String
}

struct Note: Identifiable, Codable {
    let id: String
    var content: String
    var createdAt: Date
    var isPrivate: Bool
}

struct MatchPreferences: Codable {
    var excludeFromMatching: Bool
    var excludeClientIds: [String]
}

// MARK: - Match Model

struct Match: Identifiable, Codable {
    let id: String
    var userId: String
    var client1Id: String
    var client2Id: String
    
    var score: Double // 0.0 - 1.0
    var aiReasoning: String
    var sharedInterests: [String]
    var matchType: MatchType
    
    var status: MatchStatus
    var introducedAt: Date?
    var outcome: String?
    
    var createdAt: Date
    var updatedAt: Date
}

enum MatchType: String, Codable {
    case professional
    case personal
    case both
}

enum MatchStatus: String, Codable {
    case suggested
    case approved
    case introduced
    case rejected
    case successful
}

// MARK: - Communication Model

struct Communication: Identifiable, Codable {
    let id: String
    var userId: String
    var clientId: String
    
    var type: CommunicationType
    var purpose: String
    var status: CommunicationStatus
    
    var aiGenerated: AIContent?
    var finalContent: String?
    
    var sentAt: Date?
    var createdAt: Date
}

enum CommunicationType: String, Codable {
    case email
    case birthday
    case anniversary
    case introduction
    case newsletter
    case custom
}

enum CommunicationStatus: String, Codable {
    case draft
    case approved
    case sent
    case failed
}

struct AIContent: Codable {
    var content: String
    var generatedAt: Date
    var promptContext: String
    var modelVersion: String
}

// MARK: - Event Model

struct ClientEvent: Identifiable, Codable {
    let id: String
    var userId: String
    var clientId: String
    
    var type: EventType
    var title: String
    var date: Date
    var isRecurring: Bool
    var reminderDays: Int
    
    var lastTriggeredAt: Date?
    var createdAt: Date
}

enum EventType: String, Codable {
    case birthday
    case anniversary
    case followUp
    case custom
}

// MARK: - User Model

struct AppUser: Identifiable, Codable {
    let id: String
    var email: String
    var displayName: String
    var firmName: String?
    
    var settings: UserSettings
    var subscription: Subscription
    
    var createdAt: Date
}

struct UserSettings: Codable {
    var defaultReminderDays: Int
    var communicationTone: String // "formal", "casual", "warm"
    var signatureTemplate: String?
    var notificationsEnabled: Bool
}

struct Subscription: Codable {
    var tier: SubscriptionTier
    var expiresAt: Date?
    var aiCreditsRemaining: Int?
}

enum SubscriptionTier: String, Codable {
    case free
    case pro
    case enterprise
}

3.2 Firestore Collections Structure

firestore/
├── users/
│   └── {userId}/
│       ├── profile (document fields)
│       ├── settings (document fields)
│       └── subscription (document fields)
│
├── clients/
│   └── {clientId}/
│       ├── (all client fields)
│       └── notes[] (embedded array)
│
├── matches/
│   └── {matchId}/
│       └── (all match fields)
│
├── communications/
│   └── {communicationId}/
│       └── (all communication fields)
│
├── events/
│   └── {eventId}/
│       └── (all event fields)
│
└── auditLog/
    └── {logId}/
        ├── userId
        ├── action
        ├── resourceType
        ├── resourceId
        ├── timestamp
        └── metadata

---

4. API Endpoints (Cloud Functions)

4.1 AI Endpoints

POST /api/ai/generateEmail
Request:
{
  "clientId": "abc123",
  "purpose": "birthday",
  "additionalContext": "mention wine discussion"
}
Response:
{
  "content": "Dear John, ...",
  "generatedAt": "2025-06-26T10:00:00Z",
  "communicationId": "comm123"
}

POST /api/ai/suggestMatches
Request:
{
  "clientId": "abc123",  // optional, for specific client
  "limit": 10
}
Response:
{
  "matches": [
    {
      "client1Id": "abc123",
      "client2Id": "def456",
      "score": 0.87,
      "reasoning": "Both avid golfers...",
      "sharedInterests": ["golf", "stanford"]
    }
  ]
}

POST /api/ai/generateIntroduction
Request:
{
  "matchId": "match123"
}
Response:
{
  "emailToClient1": "...",
  "emailToClient2": "...",
  "communicationIds": ["comm1", "comm2"]
}

4.2 Data Endpoints

GET /api/clients
GET /api/clients/{clientId}
POST /api/clients
PUT /api/clients/{clientId}
DELETE /api/clients/{clientId}

GET /api/events/upcoming?days=7
POST /api/events

GET /api/matches?status=suggested
PUT /api/matches/{matchId}/status

POST /api/communications/{commId}/send

GET /api/export/client/{clientId}  // GDPR
DELETE /api/data/client/{clientId}  // GDPR right to deletion

4.3 Cloud Functions Structure

// functions/index.js

const functions = require('firebase-functions');
const admin = require('firebase-admin');
const Anthropic = require('@anthropic-ai/sdk');

admin.initializeApp();

// AI Email Generation
exports.generateEmail = functions.https.onCall(async (data, context) => {
  // Verify authentication
  if (!context.auth) {
    throw new functions.https.HttpsError('unauthenticated', 'Must be logged in');
  }
  
  // Get client data
  const client = await getClient(data.clientId, context.auth.uid);
  
  // Build prompt
  const prompt = buildEmailPrompt(client, data.purpose, data.context);
  
  // Call Claude
  const anthropic = new Anthropic();
  const response = await anthropic.messages.create({
    model: 'claude-3-5-sonnet-20241022',
    max_tokens: 1024,
    messages: [{ role: 'user', content: prompt }]
  });
  
  // Save draft and return
  const commId = await saveDraft(context.auth.uid, data.clientId, response);
  
  // Audit log
  await logAction(context.auth.uid, 'ai_generate', 'communication', commId);
  
  return { content: response.content[0].text, communicationId: commId };
});

// Scheduled: Daily event check
exports.checkDailyEvents = functions.pubsub
  .schedule('0 8 * * *')
  .timeZone('America/New_York')
  .onRun(async (context) => {
    const events = await getUpcomingEvents(7);
    await sendEventNotifications(events);
  });

---

5. Development Phases

Phase 1: Foundation (Weeks 1-4)

Week 1-2: Project Setup

• Create Xcode project with SwiftUI
• Set up project architecture (folders, protocols)
• Configure Firebase project
• Implement Firebase Authentication
• Set up CI/CD (GitHub Actions + TestFlight)

Week 3-4: Core Data Layer

• Create all Swift models
• Implement Firestore service
• Build repository layer
• Enable offline persistence
• Implement basic CRUD for clients

Deliverables:

• App shell with authentication
• Can create/read clients (no UI polish)
• Offline storage working

---

Phase 2: Core Features (Weeks 5-8)

Week 5-6: Client Management UI

• Client list view with search
• Client detail view (full profile)
• Client edit/create forms
• Notes management
• Tags and filtering

Week 7-8: Events & Notifications

• Event model and storage
• Birthday/anniversary detection
• Local notifications setup
• Push notifications (Firebase Cloud Messaging)
• Dashboard with upcoming events

Deliverables:

• Fully functional CRM (without AI)
• Can manage clients, notes, events
• Receives reminders for birthdays

---

Phase 3: AI Integration (Weeks 9-12)

Week 9-10: AI Infrastructure

• Set up Cloud Functions
• Claude API integration
• Prompt engineering and testing
• Rate limiting and error handling

Week 11-12: AI Features

• Email generation UI
• Review/edit/approve workflow
• Match suggestion algorithm
• Match review UI
• Introduction email generation

Deliverables:

• AI email generation working
• Match suggestions with explanations
• Full AI workflow complete

---

Phase 4: Polish & Compliance (Weeks 13-16)

Week 13-14: Compliance

• Data export feature (GDPR)
• Account deletion flow
• Audit logging
• Security hardening
• Biometric authentication

Week 15-16: Polish

• UI refinements
• Animation and transitions
• Edge case handling
• Performance optimization
• Comprehensive testing
• App Store assets
• TestFlight beta

Deliverables:

• Production-ready application
• App Store submission ready
• Documentation complete

---

6. File Structure

NetworkApp/
├── App/
│   ├── NetworkApp.swift
│   └── AppDelegate.swift
│
├── Core/
│   ├── Models/
│   │   ├── Client.swift
│   │   ├── Match.swift
│   │   ├── Communication.swift
│   │   ├── Event.swift
│   │   └── User.swift
│   │
│   ├── Services/
│   │   ├── FirebaseService.swift
│   │   ├── AuthService.swift
│   │   ├── AIService.swift
│   │   └── NotificationService.swift
│   │
│   ├── Repositories/
│   │   ├── ClientRepository.swift
│   │   ├── MatchRepository.swift
│   │   └── EventRepository.swift
│   │
│   └── Utilities/
│       ├── Extensions/
│       ├── Helpers/
│       └── Constants.swift
│
├── Features/
│   ├── Authentication/
│   │   ├── Views/
│   │   └── ViewModels/
│   │
│   ├── Dashboard/
│   │   ├── Views/
│   │   └── ViewModels/
│   │
│   ├── Clients/
│   │   ├── Views/
│   │   │   ├── ClientListView.swift
│   │   │   ├── ClientDetailView.swift
│   │   │   └── ClientEditView.swift
│   │   └── ViewModels/
│   │       └── ClientsViewModel.swift
│   │
│   ├── Matches/
│   │   ├── Views/
│   │   └── ViewModels/
│   │
│   ├── Communications/
│   │   ├── Views/
│   │   └── ViewModels/
│   │
│   └── Settings/
│       ├── Views/
│       └── ViewModels/
│
├── Resources/
│   ├── Assets.xcassets
│   ├── Localizable.strings
│   └── Info.plist
│
└── Tests/
    ├── UnitTests/
    └── UITests/

---

7. Testing Strategy

Unit Tests

• Model encoding/decoding
• Repository logic
• AI prompt building
• Date/event calculations

Integration Tests

• Firebase read/write
• AI service calls
• Authentication flows

UI Tests

• Critical user journeys
• Client CRUD operations
• AI generation flow

Manual Testing

• Various client data scenarios
• Offline/online transitions
• Edge cases

---

8. Launch Checklist

• All features tested on device
• Performance profiled (Instruments)
• Memory leaks checked
• Crash-free for 48+ hours
• App Store screenshots (6.5" & 5.5")
• App Store description
• Privacy policy URL
• Support URL
• App Review notes
• TestFlight beta feedback addressed
• Analytics events verified
• Crashlytics configured