CodePlans

Coordinate and track changes across your software architecture.

CodePlans is an open-source engineering planning tool that helps teams manage coordinated code changes across complex systems. It organises work in a clear hierarchy — Products → Assets → Code Plans → Tasks — giving teams a shared view of what's changing, where, and why.

→ Beta signup: codeplans.ai · Docs: sylonzero.github.io/CodePlans

Why CodePlans?

Modern engineering teams struggle with change coordination across distributed codebases. Tickets track individual tasks but miss the bigger picture; architecture docs go stale; migrations and refactors span multiple services with no shared source of truth.

CodePlans sits between your issue tracker and your architecture diagram:

Products group your system's components under a planning boundary
Assets represent individual components (apps, services, libraries, datastores, platforms) with health and tech debt tracking
Code Plans coordinate related changes across assets with assignees, deadlines, and progress tracking
Tasks are the individual units of work tied to a plan and optionally scoped to a specific asset

Features

Feature	Status
Products & asset inventory	✅ Available
Product, asset, plan & task create/edit (side panels & quick modals)	✅ Available
Workspace product switcher (filter all pages by product)	✅ Available
Tech debt scoring per asset	✅ Available
Code Plans with status lifecycle (draft → active → completed)	✅ Available
Task management (list & kanban views, deep-linkable task panel)	✅ Available
Dashboard with velocity metrics	✅ Available
Organization & team management	✅ Available
Role-based access (owner / admin / editor / viewer)	✅ Available
SQLite local mode (no cloud required)	✅ Available
Supabase + Postgres cloud mode	✅ Available
Pluggable auth (local password or Supabase)	✅ Available
Analytics (velocity, effort accuracy, tech debt trends)	🚧 In progress
Asset dependency graph	🚧 In progress
Activity feed	🚧 In progress
AI-assisted effort estimation	🔜 Planned
Billing / subscription management	🔜 Planned (optional, feature-flagged)

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router, Server Components)
Language	TypeScript 5.7
Styling	Tailwind CSS v4 + Radix UI primitives
ORM	Drizzle ORM
Database	SQLite (local / libsql) or PostgreSQL (cloud)
Auth	Local (bcrypt + session cookie) or Supabase
Charts	Recharts
Testing	Vitest (88 tests)

Deployment Modes

CodePlans has two independent configuration axes that control how an instance behaves.

`HOST_MODE` — the deployment model

Value	Description
`team`	Single private team. One organisation, no open registration, billing UI hidden. The right default for self-hosted installs.
`saas`	Multi-tenant hosted. Multiple independent orgs can exist, open registration is possible, billing UI available.

`REGISTRATION` — who can create accounts

Value	Description
`closed`	`/signup` returns 404. Users are created by an admin via `pnpm db:seed` or a future admin CLI.
`invite`	`/signup` shows an invite-only message. (Token-based invite flow is planned.)
`open`	Anyone who can reach the server can sign up.

Common combinations

Self-hosted team (recommended default):

HOST_MODE=team
REGISTRATION=closed

Hosted SaaS with open signup:

HOST_MODE=saas
REGISTRATION=open

Closed beta / waitlist:

HOST_MODE=saas
REGISTRATION=invite

Getting Started

Prerequisites

Node.js 20+
pnpm (npm install -g pnpm)

Self-hosted team (SQLite, no cloud required)

# 1. Clone the repo
git clone https://github.com/SylonZero/CodePlans.git
cd CodePlans

# 2. Install dependencies
pnpm install

# 3. Configure environment
cp .env.example .env.local
# .env.example defaults to HOST_MODE=team, REGISTRATION=closed, SQLite — no changes needed

# 4. Run migrations and create the admin account
pnpm db:migrate
pnpm db:seed

# 5. Start the dev server
pnpm dev

Open http://localhost:3000 and sign in with:

Field	Value
Email	`admin@example.com`
Password	`Password1!`

Change your password in Settings → Security after first login.

Want realistic demo data? Run pnpm db:seed-demo after pnpm db:seed to populate the workspace with products, assets, plans, and tasks. All demo accounts use password Password1! — see Demo accounts below.

Deploying to a server? Set AUTH_URL=https://your-server-domain (or http://ip:port) in .env.local. Auth.js requires this in production to construct correct callback URLs — without it, login redirects will fail.
If running the dev server on a remote machine, also set ALLOWED_DEV_ORIGINS=your.server.ip.

Cloud (Supabase + Postgres) mode

# Set these variables in .env.local
HOST_MODE=saas
REGISTRATION=open
AUTH_PROVIDER=supabase
DB_PROVIDER=postgres
DATABASE_URL=postgresql://...
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
SUPABASE_SECRET_KEY=your-service-role-key

Then run pnpm db:migrate and pnpm dev.

Environment variables

Variable	Default	Description
`PORT`	`3000`	Port the dev server binds to
`HOST_MODE`	`saas`	`team` (private self-hosted) or `saas` (multi-tenant hosted)
`REGISTRATION`	`open`	`closed`, `invite`, or `open` — controls who can create accounts
`AUTH_PROVIDER`	`local`	`local` (bcrypt + session cookie) or `supabase`
`DB_PROVIDER`	`sqlite`	`sqlite` or `postgres`
`DATABASE_URL`	`:memory:`	SQLite: `file:data/codeplans.db` or `:memory:`. Postgres: full connection string
`DB_SSL`	`true`	Set `false` for local or non-SSL Postgres
`AUTH_SECRET`	—	Secret for local auth session signing (min 32 chars)
`AUTH_URL`	—	Required in production. Full URL of the server (e.g. `https://codeplans.yourteam.com`). Auth.js uses this to construct callback URLs and validate login redirects. Not needed for `localhost` dev.
`BILLING_ENABLED`	`true`	Set `false` to hide billing UI (always off in `team` mode)
`ALLOWED_DEV_ORIGINS`	—	Comma-separated hosts allowed to access Next.js dev resources (needed when running on a remote server)
`RESEND_API_KEY`	—	Resend API key for transactional email (email change verification, future invites). Without this, verification URLs are logged to the server console (dev only).
`RESEND_FROM_EMAIL`	`CodePlans <noreply@codeplans.ai>`	From address used in outgoing emails
`NEXT_PUBLIC_SUPABASE_URL`	—	Required for Supabase auth mode
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	—	Required for Supabase auth mode
`SUPABASE_SECRET_KEY`	—	Required for Supabase auth mode (server-side)

Project Structure

CodePlans/
├── app/                        # Next.js App Router
│   ├── (auth)/                 # Login & signup pages
│   └── (dashboard)/            # Protected app pages
│       ├── page.tsx            # Dashboard
│       ├── products/           # Product list + detail
│       ├── plans/              # Code Plans list + detail
│       ├── tasks/              # Task management
│       ├── team/               # Team & org management
│       ├── analytics/          # Analytics
│       └── settings/           # User settings
├── components/
│   ├── app-shell.tsx           # Sidebar + header layout
│   ├── dashboard/              # Dashboard widgets
│   └── ui/                     # Radix/shadcn primitives
├── lib/
│   ├── auth/                   # Pluggable auth adapters
│   ├── db/
│   │   ├── schema.sqlite.ts    # SQLite schema (Drizzle)
│   │   ├── schema.pg.ts        # Postgres schema (Drizzle)
│   │   ├── queries.ts          # Read queries
│   │   ├── mutations.ts        # Write operations
│   │   ├── migrations/         # SQL migration files
│   │   └── seed.ts             # Development seed data
│   ├── config.ts               # Environment config
│   └── types.ts                # Shared TypeScript types
├── tests/
│   ├── helpers/db.ts           # Test fixtures & helpers
│   └── lib/                    # Query & mutation tests
└── docs/                       # Technical documentation

Database Schema

The core data model:

users
  └── organizationMembers ──→ organizations
        └── products
              ├── assets
              │     └── assetDependencies
              └── codePlans
                    └── tasks

Both SQLite and Postgres schemas are maintained in parallel under lib/db/. Migrations live in lib/db/migrations/{sqlite,postgres}/.

Running Tests

pnpm test              # run all tests (88 tests across 3 files)
pnpm test:watch        # watch mode
pnpm test:coverage     # with coverage report

Tests use an in-memory SQLite database and run in isolated forked processes.

Database Scripts

pnpm db:generate       # generate migrations from schema changes
pnpm db:migrate        # apply migrations
pnpm db:push           # push schema directly (dev only)
pnpm db:studio         # open Drizzle Studio
pnpm db:seed           # create admin account + default workspace
pnpm db:seed-demo      # populate with realistic multi-user demo data

The seed scripts respect three optional env vars for the admin account:

SEED_ADMIN_EMAIL=admin@example.com   # default
SEED_ADMIN_PASSWORD=Password1!       # default
SEED_ADMIN_NAME=Admin                # default
SEED_ORG_NAME="My Workspace"         # default

Demo accounts

After running pnpm db:seed-demo, five accounts are available:

Name	Email	Role	Password
Alex Chen	`alex.chen@codeplans.local`	Owner	`Password1!`
Sarah Kim	`sarah.kim@codeplans.local`	Admin	`Password1!`
Mike Jones	`mike.jones@codeplans.local`	Editor	`Password1!`
Lisa Wang	`lisa.wang@codeplans.local`	Editor	`Password1!`
James Lee	`james.lee@codeplans.local`	Viewer	`Password1!`

The demo workspace includes 3 products, 15 assets, 9 code plans, and ~65 tasks across various stages.

Contributing

Contributions are welcome. To get started:

Fork the repo and create a feature branch
Make your changes — the SQLite local mode requires no cloud setup
Add or update tests in tests/
Open a pull request with a clear description

Please keep PRs focused. Bug fixes, test coverage improvements, and documentation updates are especially appreciated.

Roadmap

Product & asset CRUD forms — shipped in v0.1.5 (side panels & quick modals)
Code Plan create/edit flows — shipped in v0.1.5
Task create/edit panel + inline status updates — shipped in v0.1.5
Asset dependency graph visualisation
Activity feed (event log)
Analytics wired to real data
AI-assisted effort estimation
Team invite flow

See docs/app-spec.md for the full current state of the app including wiring gaps.

License

MIT — see LICENSE.

Built by Sai Prakash · Sign up for the beta

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
app		app
components		components
data		data
docs		docs
hooks		hooks
lib		lib
public		public
styles		styles
supabase/sql		supabase/sql
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
components.json		components.json
drizzle.config.ts		drizzle.config.ts
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
proxy.ts		proxy.ts
tsconfig.json		tsconfig.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

CodePlans

Why CodePlans?

Features

Tech Stack

Deployment Modes

`HOST_MODE` — the deployment model

`REGISTRATION` — who can create accounts

Common combinations

Getting Started

Prerequisites

Self-hosted team (SQLite, no cloud required)

Cloud (Supabase + Postgres) mode

Environment variables

Project Structure

Database Schema

Running Tests

Database Scripts

Demo accounts

Contributing

Roadmap

License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

CodePlans

Why CodePlans?

Features

Tech Stack

Deployment Modes

HOST_MODE — the deployment model

REGISTRATION — who can create accounts

Common combinations

Getting Started

Prerequisites

Self-hosted team (SQLite, no cloud required)

Cloud (Supabase + Postgres) mode

Environment variables

Project Structure

Database Schema

Running Tests

Database Scripts

Demo accounts

Contributing

Roadmap

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`HOST_MODE` — the deployment model

`REGISTRATION` — who can create accounts

Packages