Skip to content

Commit 87a6364

Browse files
sidmohan0sidmohan0
committed
Refresh repository README for open source onboarding
1 parent cd97d22 commit 87a6364

File tree

1 file changed

+96
-41
lines changed

1 file changed

+96
-41
lines changed

‎README.md‎

Lines changed: 96 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,53 @@
11
# Kanbun
22

3-
Kanbun is a personal contact manager for relationship-driven outreach. The product direction is a unified system that can:
3+
Kanbun is an open-source personal contact manager for relationship-driven outreach.
44

5-
- sync contacts and communication metadata from Gmail and Microsoft Outlook
6-
- import contacts from CSV into a normalized database
7-
- manage sequences, ad hoc follow-ups, and contact tasks from one application
8-
- integrate with Todoist for task capture and workflow continuity
5+
It brings contacts, follow-ups, sequences, provider sync, and operator review into one application so you can run personal CRM work without bouncing between Gmail, Outlook, CSV spreadsheets, and Todoist.
96

10-
The repository is intentionally starting with architecture and operating-model documentation before application code. The goal is to make the codebase agent-friendly, legible, and maintainable from day one.
7+
## What It Does
118

12-
## Current status
9+
- sync contacts from Gmail and Microsoft Outlook
10+
- import contacts from CSV into a canonical PostgreSQL model
11+
- create and manage ad hoc follow-ups inside the app
12+
- enroll contacts into multi-step email sequences
13+
- generate drafts, queue sends, and keep approvals supervised
14+
- detect replies and stop future sequence steps automatically
15+
- surface merge conflicts, connector issues, outbound approvals, and task exceptions in one review inbox
16+
- mirror follow-up tasks into Todoist
1317

14-
Planning is complete and the repository bootstrap is underway. The current app includes:
18+
## Current Status
1519

16-
- a Next.js 16 app-router foundation
20+
Kanbun is already runnable locally and covers the core operator loop:
21+
22+
- connect Google and Microsoft accounts
23+
- import and unify contacts
24+
- create and edit manual contacts
25+
- manage follow-ups and Todoist mirroring
26+
- create sequences, approve drafts, and send through connected accounts
27+
- review merge conflicts and connector issues
28+
29+
It is still early-stage software. The product model is strong, but the repo is not yet fully production-hardened or polished for broad public usage.
30+
31+
## Stack
32+
33+
- Next.js 16
34+
- React 19
1735
- Tailwind CSS 4
1836
- `shadcn/ui`
19-
- a Kanbun app shell with database-backed home, contacts, imports, and tasks views
20-
- local PostgreSQL scaffolding via Docker Compose
21-
- Drizzle ORM schema and migrations
22-
- owner-mode password authentication backed by PostgreSQL sessions
23-
- a robust CSV import flow with file idempotency, draft preview and remapping, per-row edits and skip controls, paginated review, downloadable review reports, and dedicated worker processing into canonical contacts
24-
- Google OAuth connected-account scaffolding with worker-driven People API contact sync into the canonical contact model
25-
- Microsoft OAuth connected-account scaffolding with worker-driven Graph contact sync into the same canonical contact model
26-
- a multi-step sequence engine with durable enrollments, worker-generated review drafts, retry/cancel controls, automatic provider reply detection, and queued outbound delivery through connected Gmail or Microsoft accounts
27-
- a unified review inbox for outbound approvals, merge conflicts, connector issues, import exceptions, and Todoist task failures
28-
- manual contact creation/editing plus search and source/attention filters on the canonical contacts list
29-
- ad hoc follow-up creation from the contact workspace into the Kanbun task queue
30-
- Todoist API-token task mirroring with worker-driven reconciliation back into Kanbun task state
31-
- baseline lint, typecheck, unit test, browser E2E, build, and CI setup
32-
33-
## Docs
34-
35-
- [Agent guide](./AGENTS.md)
36-
- [Docs index](./docs/README.md)
37-
- [ADR index](./docs/adr/README.md)
37+
- PostgreSQL
38+
- Drizzle ORM
39+
- TypeScript
3840

3941
## Quickstart
4042

43+
### Prerequisites
44+
45+
- Node.js 20+
46+
- `pnpm`
47+
- Docker
48+
49+
### Local Setup
50+
4151
```bash
4252
pnpm install
4353
cp .env.example .env.local
@@ -51,18 +61,40 @@ pnpm worker
5161
```
5262

5363
Open `http://localhost:7890`.
54-
PostgreSQL is exposed on `localhost:5433` by default to avoid collisions with an existing local database.
55-
If `OWNER_MODE_ENABLED=true`, sign in with the `OWNER_EMAIL` and `OWNER_PASSWORD` values from `.env.local`.
56-
If `OWNER_MODE_ENABLED=false`, the app bypasses sign-in for local development.
57-
Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` to enable the Gmail/People integration, Gmail send permissions, and automatic reply detection.
58-
Set `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, and optionally `MICROSOFT_TENANT_ID` to enable the Microsoft Graph integration, Outlook send permissions, and automatic reply detection.
59-
Set `TODOIST_API_TOKEN` to enable Todoist task mirroring.
60-
The app runs on port `7890` by default.
61-
Make sure `KANBUN_URL` matches the OAuth redirect origin you register with the providers.
62-
If you connected Google or Microsoft before outbound sending and reply detection were added, reconnect once so the new read/send scopes are granted.
63-
Sequence sends currently obey per-sequence send windows and a per-account daily send cap.
64-
65-
## Core commands
64+
65+
## Environment
66+
67+
### Core
68+
69+
- `KANBUN_PORT`
70+
- `KANBUN_URL`
71+
- `DATABASE_URL`
72+
- `APP_ENCRYPTION_KEY`
73+
- `OWNER_MODE_ENABLED`
74+
- `OWNER_EMAIL`
75+
- `OWNER_PASSWORD`
76+
77+
If `OWNER_MODE_ENABLED=false`, Kanbun bypasses sign-in for local development.
78+
79+
### Optional Integrations
80+
81+
- `GOOGLE_CLIENT_ID`
82+
- `GOOGLE_CLIENT_SECRET`
83+
- `MICROSOFT_CLIENT_ID`
84+
- `MICROSOFT_CLIENT_SECRET`
85+
- `MICROSOFT_TENANT_ID`
86+
- `TODOIST_API_TOKEN`
87+
88+
## OAuth Redirect URIs
89+
90+
Register these exact callback URLs in your provider apps when running locally:
91+
92+
- Google: `http://localhost:7890/api/auth/google/callback`
93+
- Microsoft: `http://localhost:7890/api/auth/microsoft/callback`
94+
95+
If you connected Google or Microsoft before send or reply-detection scopes were added, reconnect once so the newer permissions are granted.
96+
97+
## Core Commands
6698

6799
```bash
68100
pnpm lint
@@ -71,9 +103,32 @@ pnpm test
71103
pnpm test:e2e
72104
pnpm build
73105
pnpm format:fix
74-
pnpm db:generate
106+
pnpm db:up
75107
pnpm db:migrate
76108
pnpm db:seed-owner
77109
pnpm worker
78110
pnpm worker:once
79111
```
112+
113+
## Project Structure
114+
115+
- [AGENTS.md](./AGENTS.md): agent workflow and repo operating rules
116+
- [docs/README.md](./docs/README.md): documentation index
117+
- [docs/adr/README.md](./docs/adr/README.md): architectural decision records
118+
- [docs/product/README.md](./docs/product/README.md): product behavior and UX specs
119+
- [docs/plans/README.md](./docs/plans/README.md): implementation plans
120+
121+
## Contributor Notes
122+
123+
This repo is intentionally documentation-first and agent-friendly.
124+
125+
Before changing behavior, read the relevant ADRs and product docs first. The expectation is that code follows the documented operating model instead of drifting into undocumented behavior.
126+
127+
## Near-Term Work
128+
129+
The biggest remaining areas are:
130+
131+
- outbound hardening and thread-aware reply tracking
132+
- stronger contact merge and duplicate resolution tooling
133+
- more provider reliability and observability
134+
- auth cleanup and open-source polish

0 commit comments

Comments
 (0)