PocketFlow CRM

PocketFlow CRM is an iOS application built with SwiftUI that combines personal finance tracking with a lightweight CRM workflow. The project is designed around a practical business scenario: a freelancer, consultant, sales advisor, or independent professional needs to record income and expenses, associate them with clients, and prepare selected financial activity for synchronization with Salesforce.

Project Overview

The current version provides a usable finance-focused CRM experience. It includes a SwiftUI dashboard, transaction and client flows, authentication, secure token storage boundaries, financial summary calculations, SwiftData-backed local persistence, a sync queue, repository boundaries, DTO mapping, operation states, a remote HTTP client integration for the local NestJS backend, and a mock Salesforce synchronization service. The architecture is modular and review-friendly, with navigation isolated through a coordinator and business/data access logic placed behind services and repositories.

Screenshots

Core Features

• Financial dashboard with income, expense, and balance summary.
• Transaction list with expense/income classification.
• Transaction creation and detail screens.
• Client list, client creation, client detail, and client-level financial summaries.
• Login and logout flow with mock and remote repository implementations.
• Keychain-ready secure token store with testable in-memory implementation.
• Remote API client with bearer token authorization for the PocketFlow API.
• Environment-based backend switching for local development.
• Client association for CRM-style financial tracking.
• Local persistence for app data.
• SwiftData-backed entity persistence with JSON fallback strategy.
• Sync queue for pending Salesforce operations.
• Repository layer prepared for future backend integration.
• API DTO boundary with a mock API client.
• Loading, success, and failure states for sync and local persistence.
• Visible integration mode in Sync Center for mock and local backend runs.
• Backend health check from Sync Center when the local API mode is enabled.
• Sync status per transaction.
• Mock Salesforce sync service to model future API integration.
• Unit tests for financial calculations, CRM metrics, portfolio summaries, and sync behavior.

Tech Stack

• Swift 6
• SwiftUI
• MVVM-C
• Combine / ObservableObject
• SwiftData
• URLSession
• Keychain Services
• XCTest
• SwiftLint
• Fastlane
• NestJS-compatible local backend integration
• Xcode project structure

Architecture

The project follows a lightweight MVVM-C structure:

• Models: Domain entities such as Transaction, Client, and sync-related enums.
• Views: SwiftUI screens and reusable UI components. Views receive navigation actions instead of deciding app flow.
• ViewModels: UI state, session state, user actions, and coordination between views and services.
• Coordinators: App-level navigation state and typed routes. AppCoordinator owns tab-specific navigation paths and resolves client/transaction routes from AppRootView.
• Repositories: Data access and mutation boundaries for clients, transactions, persistence, and sync.
• Services: Business logic, summary calculations, queue rules, and external integration boundaries.
• Persistence: SwiftData local storage through entity records for clients, transactions, sync queue, and metadata, behind the existing persistence protocol.
• Secure Storage: SecureTokenStoring abstracts token persistence for future OAuth and uses Keychain in the app target.
• DTOs / API Client: API-facing request/response models, mock API client, and PocketFlowRemoteAPIClient backed by URLSession.
• HTTP: HTTPClientProtocol, URLSessionHTTPClient, endpoints, status-code mapping, bearer authorization, and backend payload adapters.
• Environment: AppEnvironment stores runtime configuration such as API base URL, backend mode, and UI test flags.
• Dependencies: AppDependencies assembles token storage, auth, sync, persistence, and ViewModels without coupling SwiftUI views to infrastructure setup.
• Operation State: Shared loading/success/failure state used by ViewModels and SwiftUI screens.
• Tests: Unit tests for core behavior.

This separation keeps the UI independent from business logic, makes navigation easier to evolve, and prepares the project for future persistence, networking, and authentication layers.

Salesforce Integration Approach

The app uses SalesforceSyncServiceMock by default to simulate synchronization without requiring real Salesforce credentials. This keeps the project safe to run and review while preserving a clear integration boundary.

For local API development, the app can point to the companion NestJS backend:

POCKETFLOW_USE_REMOTE_BACKEND=1 POCKETFLOW_API_BASE_URL=http://localhost:3000

When this mode is enabled, login uses POST /v1/auth/login, tokens are stored through SecureTokenStoring, and sync sends the iOS snapshot to POST /v1/sync with bearer authorization.

A production-ready Salesforce implementation would include:

• OAuth 2.0 authentication.
• Secure token storage in Keychain.
• REST API communication with Salesforce.
• Mapping local clients to Salesforce Account or Contact records.
• Mapping financial records to a Salesforce custom object.
• Error handling, retry policies, and offline sync state.

Current Status

This repository contains the iOS MVP foundation with an MVVM-C SwiftUI architecture, mock and remote session flows, repository boundaries, local persistence, and sync-ready state management. The app builds successfully for iOS Simulator, and the unit test target passes with the current project configuration.

Implemented screens:

• Login
• Dashboard / CRM overview
• Transactions
• Clients
• Client detail
• Transaction detail
• Sync Center

Quality Practices

• Modular project structure.
• Dependency container for mock/local-backend wiring.
• Coordinator-driven navigation with typed routes.
• Mock authentication flow with dedicated session ViewModel and auth repository.
• Remote auth repository compatible with the local PocketFlow API.
• Keychain-ready token storage abstraction for access and refresh tokens.
• URLSession-backed HTTP client with test coverage and API error mapping.
• SwiftData-backed entity persistence with in-memory tests.
• Basic UI test target for login and logout flows.
• Repository layer between ViewModels and data sources.
• DTO mapping between app domain models and API-facing payloads.
• User-facing operation states for loading and error handling.
• API error mapping for auth, expired sessions, server failures, and invalid responses.
• Runtime integration visibility for demos and technical review.
• Local API health check with repository abstraction and unit tests.
• Protocol-based service abstraction for Salesforce sync.
• Unit tests for core financial summary logic.
• Unit tests for service-level CRM and dashboard behavior.
• Shared test doubles for HTTP, persistence, and sync boundaries.
• API client tests for token, authorization, server, and decoding failures.
• GitHub Actions workflow for lint, unit tests, simulator build, and artifact upload.
• Fastlane lanes for local test, build, and future beta delivery.
• Mock service implementation for deterministic testing.
• No real credentials or tokens stored in the repository.

Getting Started

1. Clone the repository.
2. Open PocketFlow.xcodeproj in Xcode.
3. Select the PocketFlow scheme.
4. Run the app on an iOS Simulator.

To run against the local backend, start the PocketFlow API and add these environment variables to the Xcode scheme:

POCKETFLOW_USE_REMOTE_BACKEND=1
POCKETFLOW_API_BASE_URL=http://localhost:3000

Without those variables, the app runs in the default local/mock mode so reviewers can explore the UI without backend setup.

CI/CD

The repository includes a GitHub Actions workflow in .github/workflows/ios-build.yml with separate jobs for:

• SwiftLint validation.
• Unit tests for PocketFlowTests.
• Simulator build.
• Uploading a zipped simulator .app artifact.

Fastlane is scaffolded for local and future release automation:

bundle install
bundle exec fastlane ios test
bundle exec fastlane ios build

The beta lane is prepared for TestFlight, but requires Apple signing and App Store Connect credentials before use.

Roadmap

• Add SwiftData schema migrations as the local model evolves.
• Add filtering by date, category, client, and sync status.
• Implement a real Salesforce API client.
• Replace mock login with OAuth login flow and secure token handling.
• Add production environment configuration for PocketFlowRemoteAPIClient.
• Expand unit and UI test coverage.

Backend Direction

The recommended backend direction is documented in docs/backend-architecture.md. The suggested path is a NestJS modular monolith first, with clear module boundaries for auth, clients, transactions, sync, and Salesforce. Those modules can later evolve into microservices if deployment or scaling needs justify it.

Purpose

PocketFlow CRM was created as a portfolio project to demonstrate iOS development fundamentals, SwiftUI UI composition, MVVM-C architecture, business-domain modeling, testable service boundaries, and preparation for third-party CRM integration.