super-personal-search（超级个人搜索）

Connectify Development Guide

Set up the project

1. Install dependencies:

   npm install

1. Create .env from .env.example and set:

- OPENAI_API_KEY - REDIS_URL - APIFY_TOKEN - optional OPENAI_MODEL, PORT

1. Start Redis before running the backend.

Run the app

Prefer single-service mode when validating full user flows (dashboard + chat + API):

npm run build
npm start

Open http://localhost:3001.

Use split mode only when focusing on one side:

• Frontend only: npm run dev
• Backend only: npm run dev:server

Use the file map

• server.js: Express API, Redis seeding, /api/query, static hosting of dist/.
• agent.js: OpenAI relevance scoring and follow-up action generation.
• redis.js: Redis connection lifecycle, connection storage, query-context cache (30 min TTL).
• apify.js: Connection ingestion adapter (currently placeholder dataset).
• src/components/AIChatPanel.jsx: chat UX and /api/query client call.
• src/data/placeholders.js: dashboard placeholder cards/lists/map seed data.

Preserve the backend response contract

Return this shape from /api/query:

{
  "results": [
    {
      "name": "string",
      "role": "string",
      "company": "string",
      "platforms": ["string"],
      "relevanceScore": 0,
      "reason": "string",
      "suggestedActions": ["string", "string"]
    }
  ]
}

If changing fields, update both server.js and src/components/AIChatPanel.jsx together.

Implement real Apify ingestion

When replacing the stub in apify.js:

1. Keep output normalized to this connection schema:

- id, name, role, company, location, platforms, tags, lastInteraction, notes

1. Keep IDs stable and unique to prevent duplicate Redis records.
2. Return an array compatible with saveConnection(connection.id, connection).
3. Keep actor/network logic isolated in apify.js; avoid spreading Apify-specific code through server.js.

Tune AI behavior safely

When editing agent.js:

1. Keep response_format: { type: 'json_object' }.
2. Keep strict parsing and fallback handling (safeJsonParse, bounded score 0-100).
3. Keep deterministic-ish scoring temperature low and action generation temperature moderate.
4. Preserve fallback actions in server.js if action generation fails.

Validate changes quickly

1. Build frontend:

   npm run build

1. Start server:

   npm start

1. Smoke test query endpoint:

   curl -X POST http://localhost:3001/api/query \
     -H "Content-Type: application/json" \
     -d "{\"query\":\"Who in my network works in AI and is based in SF?\",\"sessionId\":\"local-test-session\"}"

1. Confirm the response includes ranked results and cached repeat requests return quickly.

Watch for common pitfalls

• npm run dev serves only frontend; /api/query will not work there unless a proxy/backend is also configured.
• server.js CORS currently allows http://localhost:3000; adjust if using different local origins.
• redis.js uses keys('connection:*'); avoid very large production datasets without pagination/scans.
• Do not commit secrets from .env or hardcode API tokens.