hammer/notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d390720986d58351cdf8d70643249b4ccbd441e2
notes/projects/network-app/blueprint.md
Hammer d390720986 Add Network App project documentation 
- README.md: Project overview
- requirements.md: Full feature specification
- competitors.md: Market research (Wealthbox, Affinity, Clay, etc.)
- feasibility.md: Technical assessment with Swift/Firebase/Claude architecture
- blueprint.md: Architecture diagrams, screens, data models, API endpoints, dev phases

Client: David DePoyster / NWM
Tech: Swift/SwiftUI, Firebase, Claude AI
2026-01-27 02:01:47 +00:00

870 lines
31 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
Reference in New Issue View Git Blame Copy Permalink