The problem: Relationships scatter across apps — LinkedIn connections, email threads, meeting notes, mental reminders to follow up. No single system connects who someone is with when you last talked and what to do next.
The solution: WhoWho is a local-first personal CRM accessible through three interfaces — a CLI for power users, a REST API for programmatic access, and MCP tools for natural language interaction through Claude Desktop. It tracks contacts, logs interactions, surfaces follow-ups, and bridges to Apple's ecosystem for action items.
The result: One command or natural language request to answer "Who needs my attention this week?" — with the context to make that follow-up meaningful.
This is a showcase repository. It contains architecture documentation, design decisions, and API specifications for a private project. Source code is not included. For questions about this project, please open an inquiry.
WhoWho exposes the same service layer through three distinct access patterns — CLI (Typer), REST API (FastAPI), and MCP (FastMCP) — ensuring every interface produces identical results. Whether you type whowho contact show "Alex", call GET /api/v1/contacts/1, or ask Claude "tell me about Alex," the same ContactService handles the request.
Contacts are identified by partial name match across all interfaces. The API accepts a name string or numeric ID, the MCP tools resolve names through fuzzy search, and the CLI supports partial matching. This means users never need to remember IDs — "Alex" resolves to "Alex Rivera" everywhere.
WhoWho deliberately avoids becoming a task manager. When an interaction is logged with follow_up_needed=true, Claude bridges to Apple Reminders and Calendar via the apple-mcp protocol. WhoWho is the relationship brain; Apple apps are the action layer.
| Feature | Technical Approach | Business Value |
|---|---|---|
| Contact management | SQLAlchemy 2.0 ORM, 17-field model with JSON tags | Full relationship context in one place |
| Interaction logging | FK-linked interaction records, auto-updates last_contact |
Never forget when you last spoke |
| Follow-up surfacing | Date-window queries on follow_up_needed + next_action_date |
Proactive relationship maintenance |
| Full-text search | LIKE queries across name, company, role, notes, tags | Find anyone by any detail you remember |
| Warmth scoring | 1–5 integer scale, filterable across all interfaces | Prioritize high-value relationships |
| Tag-based filtering | JSON array storage, queryable via API and CLI | Organize contacts by context (ai, recruiter, network) |
| Natural language CRM | 5 MCP tools for Claude Desktop (stdio transport) | "Log my call with Alex" just works |
| REST API | FastAPI with auto-generated OpenAPI docs, 11 endpoints | Programmatic access for any integration |
| CLI with Rich output | Typer framework, Rich tables, partial name matching | Fast terminal workflows |
| Apple ecosystem bridge | Delegates tasks/reminders to Apple apps via apple-mcp |
No duplicate task management |
Visual documentation is planned. The following describe the key views:
- CLI contact list — Rich-formatted table with name, company, warmth, last contact, tags
- CLI contact card — Detailed view with full relationship context and interaction history
- API documentation — Auto-generated Swagger UI at
/docs- MCP workflow — Claude Desktop natural language interaction with WhoWho tools
| Metric | Value |
|---|---|
| Tests | 25 passing (pytest) |
| REST endpoints | 11 + health + manifest |
| MCP tools | 5 (Claude Desktop) |
| CLI commands | 8 (contact + db subcommands) |
| Contact fields | 17 (including JSON tags) |
| Interaction types | 6 (call, email, meeting, message, linkedin, in-person) |
| Relationship types | 17 (friend through media-contact) |
| API response time | <50ms typical (local SQLite) |
| Database | SQLite (zero-config, local-first) |
| Security scan | 12-phase automated scanner |
| Layer | Technology | Purpose |
|---|---|---|
| Language | Python 3.11+ | Primary implementation |
| API Framework | FastAPI | REST API with auto-generated OpenAPI docs |
| CLI Framework | Typer + Rich | Modern CLI with rich terminal output |
| Database | SQLite | Local-first, zero-config persistent storage |
| ORM | SQLAlchemy 2.0 | mapped_column style, type-safe models |
| Migrations | Alembic | Schema versioning and evolution |
| MCP | FastMCP | Claude Desktop integration (stdio transport) |
| Validation | Pydantic v2 | Request/response schemas with field validators |
| Configuration | pydantic-settings | Environment-based config with .env support |
| Testing | pytest | Unit and integration tests with in-memory SQLite |
| CI/CD | GitHub Actions | Lint, test, and security scanning |
Full C4 architecture documentation with Mermaid diagrams is available in ARCHITECTURE.md, including:
- System context diagram
- Container architecture
- Key design decisions
- Data flow
- Security posture
- Component interaction sequences
- Complete API endpoint map
See also: API Reference for detailed endpoint and MCP tool documentation.
All Rights Reserved. This is a showcase repository for portfolio purposes. For inquiries, please open an issue.
Built by TJ Neary