# 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

```swift
// 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

```javascript
// 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