https://github.com/johnpc/social-crm
A personal relationship manager that helps you stay in touch with friends and family in a thoughtful, human way.
https://github.com/johnpc/social-crm
Last synced: 5 months ago
JSON representation
A personal relationship manager that helps you stay in touch with friends and family in a thoughtful, human way.
- Host: GitHub
- URL: https://github.com/johnpc/social-crm
- Owner: johnpc
- Created: 2025-12-21T23:54:29.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-22T01:26:15.000Z (6 months ago)
- Last Synced: 2025-12-23T11:17:03.015Z (6 months ago)
- Language: TypeScript
- Homepage: https://crm.jpc.io
- Size: 3.63 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# jpc.crm
A personal relationship manager that helps you stay in touch with friends and family in a thoughtful, human way.
## Screenshots
## Purpose
This app is designed around kindness, emotional warmth, and reducing mental load around staying connected to people you care about. It's not about productivity, hustle, or networking—it's about being a better friend and family member without stress.
## Core Philosophy
- **Gentle and supportive** - Never guilt-driven or pushy
- **Human-controlled** - Level 1 assistance only (suggests, never autopilots)
- **Private and personal** - Your relationships, your data
- **Warm tone** - "This might feel good" instead of "You're overdue"
## Features
### MVP Features
- **Contact Management** - Add people with relationship tags and preferred contact cadence
- **Gentle Reminders** - See who might be nice to reconnect with (never "overdue")
- **Message Suggestions** - Draft warm, natural check-in messages in your tone
- **Simple Logging** - Mark "we talked" with optional notes for future context
### Contact Information
Each person can have:
- Name and relationship tag (friend, family, coworker, etc.)
- Preferred cadence (weekly/monthly/quarterly/yearly)
- Last contacted date
- Optional life context notes ("started new job", "loves hiking")
### Friendly States
Instead of "overdue," the app uses gentle language:
- "Still fresh"
- "Nice time soon"
- "Could be a nice time to reconnect"
### Message Drafting
Generates suggestions for:
- Short, warm check-in messages
- Friendly invites to coffee/chat/hang out
- All messages feel human, casual, and kind
- You always edit and send yourself
## What This App Will NOT Do
- Fully automated messaging
- Pretend to be you without approval
- Creepy data scraping
- Spammy or pushy notifications
## Development
```bash
npm install
npx ampx sandbox # Start Amplify backend
npm run dev # Start frontend
```
### First Time Setup
1. Install dependencies: `npm install`
2. Start Amplify backend: `npx ampx sandbox`
3. In a new terminal, start frontend: `npm run dev`
### Adding UI Components
Use shadcn/ui components for consistent design:
```bash
npx shadcn@latest add [component-name]
```
### Available Scripts
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run lint` - Check for linting errors
- `npm run lint:fix` - Fix linting errors
- `npm run format` - Format code with Prettier
### Code Quality
- ESLint with TypeScript and React rules
- Prettier for consistent formatting
- Pre-commit hooks with lint-staged
- No `any` types allowed
## Instructions for LLMs
### Code Organization
- **Single-purpose files** - Each helper file should have one clear responsibility
- **Size limit** - Keep files under ~200 lines; break into smaller pieces when approaching this limit
- **Logical grouping** - Related functionality should be grouped together but not in monolithic files
### State Management & Data Flow
- **React Hooks** - Use custom hooks for reusable logic
- **Provider Pattern** - Use React Context providers for shared state
- **React Query/TanStack** - Use for server state management with Amplify subscriptions
- **Real-time Updates** - Amplify subscriptions automatically update React Query cache
- **Avoid prop drilling** - Prefer context providers and hooks over passing props through multiple levels
### TypeScript Guidelines
- **Never use `any`** - This will cause linting errors
- **Define proper types** - Create interfaces and types for all data structures
- **Inline types acceptable** - If needed for quick fixes, inline types are better than `any`
- **Type safety first** - Prefer compile-time safety over runtime flexibility
### Backend & AI Integration
- **Amplify Gen2** - Use for all database operations and backend functions
- **Strands SDK** - Use TypeScript SDK for any agentic or AI workflows (message generation, etc.)
### UI Components & Theming
- **shadcn/ui** - Use for all UI components; clean, accessible, and customizable
- **Tailwind CSS v3** - For styling and layout (standard version, not v4)
- **Flat UI Design** - Use solid colors, avoid gradients. Prefer slate/blue color palette
- **Color Strategy**:
- Primary brand: `blue-600` with `blue-700` hover states
- Text: `slate-900` for headings, `slate-600` for body text
- Backgrounds: `slate-50` for page backgrounds, `white` for cards
- Borders: `slate-200` for subtle borders
- **Theming Notes**:
- Avoid gradients and glass morphism effects
- Use clean, minimal flat design
- Stick to the slate/blue palette for consistency
- Remove unnecessary visual elements (like colored circles around icons)
- **Forms** - Use shadcn/ui Form components (includes React Hook Form + Zod validation)
### Additional Libraries
- **React Router** - Use for navigation between pages/views
- **date-fns** - Use for date calculations and cadence logic
### Example Patterns
```typescript
// Good: Proper interface
interface Contact {
id: string;
name: string;
relationshipTag: string;
}
// Acceptable: Inline type
const handleSubmit = (data: { name: string; email: string }) => { ... }
// Never: Using any
const badFunction = (data: any) => { ... } // ❌ Will cause lint error
```
### Command Execution Guidelines
- **Background processes** - Always pipe long-running commands to files to prevent blocking:
```bash
npm run dev > dev.log 2>&1 &
npx ampx sandbox --once # Use --once flag to prevent blocking
```
- **Find commands** - Always exclude node_modules unless specifically searching there:
```bash
find . -name "*.ts" -not -path "./node_modules/*"
```
- **Build validation** - Run `npm run build` after significant code changes to ensure build passes
- **Environment variables** - Use dotenv library, keep `.env` and `.env.example` files updated
- **Backend changes** - Run `npx ampx sandbox --once` after modifying Amplify backend definitions
- **Visual testing** - Use Playwright MCP to visit pages and verify styling/functionality works correctly