ten31-database/venture-crm-prompt.md

Venture Fund CRM — Project Context for Claude

You are continuing development on a self-hosted CRM system for a venture fund. Below is everything you need to know about what has been built, how it works, and what comes next.

---

Business Context

• Fund: ~$200M AUM, currently fundraising for Fund II
• Users: Team of 5 people, accessing via browser on local network or remotely via Tailscale VPN
• Current LPs: 150 investors
• Prospects: 250+ being tracked
• Migrating from: Airtable (CSV exports available)
• Core goals:
  1. Eliminate sensitive LP/prospect data from third-party servers (Airtable, CRMs)
  2. Stop paying monthly subscription costs
  3. Purpose-built tool for fundraising workflow: managing existing investors, tracking new prospects, raising capital
• User: Grant (grant@ten31.xyz)

---

What Has Been Built (Sprint 1 — Complete)

A fully functional prototype with backend API, frontend UI, demo data, and utility scripts. Everything runs locally with zero external dependencies beyond two Python packages.

Tech Stack (Actual — differs from original plan)

The original plan called for FastAPI + SQLAlchemy + separate React build, but the build environment lacked pip/npm access. The stack was adapted to:

• Backend: Python 3 stdlib HTTP server + sqlite3 + bcrypt + PyJWT — single file, no framework
• Database: SQLite with WAL mode (concurrent reads, serialized writes — fine for 5 users)
• Frontend: Single self-contained HTML file loading React 18 + Babel from CDN (unpkg)
• Deployment: Run python3 backend/server.py — serves both API and frontend on port 8080
• Remote access: Tailscale mesh VPN (each device gets a private IP, peer-to-peer encrypted)

Project Structure

venture-crm/
├── backend/
│   ├── server.py              # Complete API server (1,873 lines)
│   └── requirements.txt       # bcrypt, PyJWT (for reference)
├── frontend/
│   └── index.html             # Complete React SPA (2,982 lines)
├── data/
│   └── crm.db                 # SQLite database (created on first run)
├── scripts/
│   ├── create_user.py         # CLI tool to add users
│   ├── reset_password.py      # CLI tool to reset passwords
│   └── backup.sh              # Database backup with 30-day retention
└── start.sh                   # Launch script

Database Schema

All tables use TEXT primary keys (8-char UUIDs). The database is at data/crm.db.

Tables:

• users — id, username, email, password_hash, full_name, role (admin/manager/member), is_active
• contacts — id, first_name, last_name, email, phone, mobile, title, organization_id (FK), contact_type (investor/prospect/advisor/other), status, source, tags (JSON), notes, linkedin_url, preferred_contact, created_by (FK)
• organizations — id, name, type, industry, website, phone, email, address, city, state, country, description, tags (JSON), created_by (FK)
• opportunities — id, name, contact_id (FK), organization_id (FK), stage (lead/outreach/meeting/due_diligence/committed/funded), commitment_amount, expected_amount, probability, expected_close_date, fund_name, description, next_step, owner_id (FK), priority (low/medium/high), lost_reason
• communications — id, contact_id (FK), opportunity_id (FK), type (email/call/meeting/note/text), subject, body, communication_date, duration_minutes, outcome, next_action, next_action_date, attendees (JSON), created_by (FK)
• lp_profiles — id, contact_id (FK, unique), commitment_amount, funded_amount, commitment_date, fund_name, investor_type, accredited, legal_docs_signed, signed_date, wire_received, wire_date, k1_sent, preferred_communication, notes
• custom_fields — id, name, entity_type, field_type, options (JSON), required, display_order
• custom_field_values — id, custom_field_id (FK), entity_id, entity_type, value
• audit_log — id, user_id (FK), entity_type, entity_id, action, changes (JSON), created_at
• tags — id, name (unique), color

Key indexes: contacts(contact_type, status, organization_id), opportunities(stage, owner_id, contact_id), communications(contact_id, communication_date), audit_log(entity_type, entity_id), lp_profiles(contact_id)

API Endpoints

All endpoints except auth require Authorization: Bearer <jwt_token> header. Server runs at http://0.0.0.0:8080.

Auth:

• POST /api/auth/login — body: {username, password} → {token, user}
• POST /api/auth/register — body: {username, password, email, full_name} → {token, user}

Contacts:

• GET /api/contacts?type=&status=&search=&sort=&order=&limit=&offset=&organization_id=&tag= → {data[], total, limit, offset}
• GET /api/contacts/:id → {data: {contact + communications[], opportunities[], lp_profile}}
• POST /api/contacts — full CRUD
• PUT /api/contacts/:id
• DELETE /api/contacts/:id

Organizations:

• GET /api/organizations?search=&type=&limit=&offset= → {data[], total}
• GET /api/organizations/:id → {data: {org + contacts[], opportunities[]}}
• POST /api/organizations — full CRUD
• PUT /api/organizations/:id
• DELETE /api/organizations/:id

Opportunities (Pipeline):

• GET /api/opportunities?stage=&owner_id=&search=&priority=&fund_name=&limit=&offset= → {data[], total}
• GET /api/opportunities/:id → {data: {opp + communications[], stage_history[]}}
• POST /api/opportunities
• PUT /api/opportunities/:id
• PATCH /api/opportunities/:id/stage — body: {stage} (logs stage change in audit)
• DELETE /api/opportunities/:id

Communications:

• GET /api/communications?contact_id=&type=&search=&limit=&offset= → {data[], total}
• GET /api/contacts/:id/communications → same as above, scoped to contact
• POST /api/communications
• PUT /api/communications/:id
• DELETE /api/communications/:id

LP Profiles:

• GET /api/lp-profiles?fund_name=&search= → {data[], total}
• GET /api/lp-profiles/:id → {data}
• POST /api/lp-profiles — also sets contact type to 'investor'
• PUT /api/lp-profiles/:id

Reports:

• GET /api/reports/dashboard → {metrics, pipeline_stages[], recent_communications[], upcoming_actions[], recent_stage_changes[]}
• GET /api/reports/pipeline → {by_stage[], by_owner[], by_priority[]}
• GET /api/reports/lp-breakdown → {lps[], summary, by_type[]}
• GET /api/reports/activity?days=30 → {by_user[], by_day[]}

Import/Export:

• POST /api/import/csv — body: {data: [...objects], entity_type, mapping: {csv_col: crm_field}, dry_run: bool}
• GET /api/export/contacts → {data[]}

Other:

• GET /api/tags / POST /api/tags
• GET /api/users
• GET /api/audit-log?entity_type=&entity_id=
• GET /api/health

Frontend Pages

The frontend is a single HTML file with inline CSS (dark theme) and React via CDN. Pages:

1. Login — username/password form, registration option
2. Dashboard — KPI cards (Total LPs, Committed $, Pipeline Value, Active Opportunities, Prospects, Monthly Comms), pipeline stage visualization, recent communications, upcoming actions, recent stage changes
3. Contacts — tabbed (All/Investors/Prospects), searchable sortable table, slide-over detail panel with communications timeline and opportunities, add/edit modal
4. Pipeline — Kanban-style board (Lead → Outreach → Meeting → DD → Committed → Funded), stage summary bar with $ per stage, opportunity cards with stage selector, add/edit modal
5. Communications — chronological list, filter by type/contact, log new communication form
6. LP Tracker — summary cards (Total Committed, Funded, Avg Check, LP Count), table with status indicators (checkmarks) for docs/wire/K1
7. Import — CSV paste/upload, preview table, field mapping interface, dry-run validation, execute import
8. Settings — user profile, tag management

Demo Data (Seeded Automatically)

On first run, the server seeds:

• 2 users: admin/admin123 (admin role), grant/password (admin role)
• 8 organizations (Sovereign Wealth Holdings, Pacific Capital Partners, Northeast Pension Fund, Redwood Endowment, Atlas Family Office, Summit Insurance Group, Cascade Wealth Management, Blue Harbor Foundation)
• 12 contacts (6 investors, 6 prospects)
• 6 LP profiles totaling $83M committed (all Fund I, all fully funded)
• 6 pipeline opportunities totaling $40M expected (Fund II prospects at various stages)
• 8 communication records (emails, calls, meetings)
• 6 tags (High Priority, Fund I LP, Fund II Prospect, Family Office, Institutional, Re-up Target)

How to Run

pip3 install bcrypt PyJWT
cd venture-crm
python3 backend/server.py
# Open http://localhost:8080
# Login: grant / password

What Has Been Tested

All API endpoints have been verified via curl:

• Auth (login, register)
• Contact CRUD + search
• Organization CRUD
• Opportunity CRUD + stage changes
• Communication CRUD
• LP profile CRUD
• Dashboard, pipeline, LP breakdown reports
• CSV import with dry-run and field mapping
• Frontend serves correctly from the backend

---

What Has NOT Been Built Yet (Remaining Sprints)

Sprint 2 items still needed:

• Custom fields UI (backend schema exists but not wired to frontend forms)
• Drag-and-drop on pipeline board (currently uses dropdown stage selector)

Sprint 3: Airtable Migration + Custom Fields

• Custom field definition admin UI
• Display custom fields on contact/opportunity forms
• Actual Airtable data migration (import wizard exists but hasn't been used with real data)

Sprint 4: Reporting + Polish

• Pipeline analytics (deal velocity, conversion rates between stages)
• User activity report page
• CSV export buttons on all reports
• Bulk actions on contact list (tag multiple, assign, bulk export)
• Automated daily backup via cron
• Team setup documentation

Future Enhancements (discussed but not planned):

• Email integration (auto-log emails via IMAP)
• Calendar sync
• Task assignments linked to opportunities
• Bulk email with templates
• Two-factor authentication
• Advanced saved search filters
• Audit trail UI page

---

Architecture Decisions & Constraints

1. Single-file backend: The Python server is one file (server.py) using stdlib http.server. No framework. This keeps deployment dead simple but means no middleware pattern, no auto-docs, no async. If the codebase grows significantly, consider migrating to FastAPI.

2. Single-file frontend: The React app is one HTML file loading from CDN. No build step. This means no TypeScript, no tree-shaking, no code splitting. Babel compiles JSX in the browser. If the UI grows significantly, consider splitting into a proper Vite/React project.

3. SQLite WAL mode: Handles 5 concurrent readers + 1 writer. Fine for this team size. If the team grows past 10-15, migrate to PostgreSQL.

4. No localStorage: JWT token stored in React state only (memory). Page refresh = re-login. This is intentional for security.

5. 8-char UUIDs: Generated via uuid.uuid4()[:8]. Collision probability is negligible at this data scale.

6. Tailscale for remote access: Server binds to 0.0.0.0. Tailscale gives each device a 100.x.x.x IP. No port forwarding, no public exposure.

---

Key Files to Read

When making changes, these are the files:

• backend/server.py (1,873 lines) — ALL backend logic: database schema, auth, every API endpoint, seed data, server startup. Search for handler method names like handle_list_contacts, handle_create_opportunity, etc.

• frontend/index.html (2,982 lines) — ALL frontend logic: CSS styles, React components, API client, every page. Search for component names like Dashboard, ContactsPage, PipelinePage, etc.

• scripts/create_user.py — CLI to add team members

• scripts/backup.sh — Database backup with rotation

• start.sh — Launch script

---

Common Modification Patterns

Adding a new field to contacts:

1. In server.py: add column to CREATE TABLE, add to INSERT/UPDATE in handler methods
2. In index.html: add field to the contact form component and detail view
3. Delete data/crm.db to recreate schema (or use sqlite3 ALTER TABLE)

Adding a new pipeline stage:

1. In server.py: add to PIPELINE_STAGES list
2. In index.html: add to the stages array in the Pipeline component

Changing the color scheme:

1. In index.html: modify the CSS variables in the <style> tag (search for hex colors like #0f172a, #1e293b, #6366f1)

Adding a new API endpoint:

1. In server.py: add route matching in do_GET/do_POST/etc., then add handler method

Adding a new page:

1. In index.html: create a new component, add it to the navigation sidebar and the page router