{"id":48793241,"url":"https://github.com/richardguerre/flow","last_synced_at":"2026-04-13T21:11:18.768Z","repository":{"id":65244419,"uuid":"556583708","full_name":"richardguerre/flow","owner":"richardguerre","description":"A plugin-based daily planner to keep you in the flow. ","archived":false,"fork":false,"pushed_at":"2025-09-07T11:19:56.000Z","size":7436,"stargazers_count":6,"open_issues_count":12,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-07T12:20:55.305Z","etag":null,"topics":["express","graphql","node","pothos","prisma","reactjs","tailwindcss","typescript"],"latest_commit_sha":null,"homepage":"https://flow-google-calendar-api.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/richardguerre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-10-24T05:58:07.000Z","updated_at":"2025-09-07T11:18:59.000Z","dependencies_parsed_at":"2024-03-29T01:24:30.494Z","dependency_job_id":"8c74f038-0040-4274-98a4-3a61ad03d154","html_url":"https://github.com/richardguerre/flow","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/richardguerre/flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richardguerre%2Fflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richardguerre%2Fflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richardguerre%2Fflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richardguerre%2Fflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/richardguerre","download_url":"https://codeload.github.com/richardguerre/flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richardguerre%2Fflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31770942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","graphql","node","pothos","prisma","reactjs","tailwindcss","typescript"],"created_at":"2026-04-13T21:11:18.034Z","updated_at":"2026-04-13T21:11:18.755Z","avatar_url":"https://github.com/richardguerre.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flow 🌊\n\n\u003e Stay in the flow.\n\n## What is flow?\n\nFlow is a personal daily planner to keep you in the flow. \n\nFeatures:\n\n- 📊 Kanban board: drag and drop tasks between days.\n- 🧾 Lists \u0026 items: add items to lists and drag them into your day once you're ready to do them.\n- 📕 Routines: start your day the right way with a morning routine.\n- 🧩 Plugin-based: you can install and create plugins to extend Flow's functionality.\n- 💯 Open source: Flow is open source project, so you can contribute to it and make it better.\n\n# Contributing\n\nIf you have suggestions for how Flow could be improved, or want to report a bug, [open an issue](https://github.com/richardguerre/flow/issues/new)! All contributions are welcome.\n\n## Working with Claude Code \u0026 Conductor\n\nFlow is optimized for development with [Claude Code](https://claude.com/claude-code) and [Conductor](https://conductor.build). All documentation for AI-assisted development is in the `.claude-code/` directory:\n\n- **`.claude-code/instructions.md`** - Main reference for development workflows, commands, and conventions\n- **`.claude-code/setup.md`** - Environment setup and troubleshooting\n- **`.claude-code/conventions.md`** - Code style guide (includes the no-destructuring rule)\n- **`.claude-code/architecture.md`** - System architecture and design decisions\n- **`.claude-code/plugin-development.md`** - Complete guide to building plugins\n\n### Key Things to Know\n\n**Critical Workflows:**\n- Always run `bun relay` after GraphQL schema changes\n- Always run `bun run format` before committing\n- When installing plugins, temporarily remove `--watch` flag from server (see plugin development guide)\n\n**Code Conventions:**\n- No object destructuring (except React hooks and arrays) - see conventions.md for details\n- Use `props.value` instead of destructuring\n- Tests are not maintained yet (skip for now)\n\n**Development Servers:**\n- Standard: `cd apps/server \u0026\u0026 bun dev` + `cd apps/web \u0026\u0026 bun dev`\n- Plugin dev: Add `cd apps/plugin-dev \u0026\u0026 bun dev` (serves plugins with hot-reload)\n- OAuth testing: Use ngrok for plugin-apps\n\nSee `.claude-code/instructions.md` for complete workflows and troubleshooting.\n\n## Getting started with GitHub Codespaces\n\n\u003e [!NOTE]\n\u003e Since migrating to bun, the setup for GitHub Codespaces has not been maintained. It may or may not work.\n\u003e The Codespaces setup is not the primary focus of the project right now, but if you want to help with it, please open an issue describing the problems you faced. If you want to help fix it, please open a PR.\n\nYou can create a GitHub Codespace from this repository by clicking the green button at the top of the page and selecting \"New codespace\". This will create a Codespace with with everything you need to start developing on Flow:\n\n- Starts a Postgres database on port 5432\n- Seeds the database with some data (go to apps/server/prisma/seed.ts to see what it creates).\n- Starts the `server` app in watch on port 4000\n- Starts the `web` app in watch on port 3000 and connects to the `server` app on port 4000\n\nWhen you open the web app in the browser, you may see nothing or \"Hello world\". To fix this you will need to:\n\n1. Open the web app at http://localhost:3000\n2. You should now see the app with some tasks already created.\n\n## Getting started\n\n1. Fork and clone the repository\n2. Install dependencies:\n   ```bash\n   bun install\n   ```\n3. Start a Postgres database\n4. Copy the `.env.example` file in `apps/server` into a `.env` file and modify the `DATABASE_URL` environment variable to point to your database\n   ```bash\n    cp apps/server/.env.example apps/server/.env\n    ```\n5. Run the migrations\n   ```bash\n   bun db:dev\n   ```\n   or reset it if you have already run it before. This will also seed the database with some data so you can skip the next step.\n   ```bash\n   bun db:reset\n   ```\n6. (optional) Seed the database\n   ```bash\n   bun db:seed\n   ```\n7. Copy the `.env.example` file in `apps/web` into a `.env` file. No need to modify anything.\n   ```bash\n    cp apps/web/.env.example apps/web/.env\n    ```\n8. Start the `server` and `web` app\n   ```bash\n   bun dev\n   ```\n9. Open the web app at http://localhost:3000\n10. You should now see the app with some tasks already created.\n\n## VS Code Extensions\n\nIf you are using VS Code, you will be prompted to install the recommended extensions, which you can find in `.vscode/extensions.json`. These extensions are:\n\n- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for formatting.\n- [Relay](https://marketplace.visualstudio.com/items?itemName=meta.relay) for [Relay GraphQL](https://relay.dev) support.\n- [UnoCSS](https://marketplace.visualstudio.com/items?itemName=bradlc.antfu.unocss) for [UnoCSS](https://unocss.dev) support.\n- [Prisma](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) for [Prisma](https://www.prisma.io) support.\n\n## Running tests\n\n\u003e [!NOTE]\n\u003e Since migrating to bun, the tests have not been maintained. They may or may not work.\n\u003e Test are not the primary focus of the project right now.\n\nTo run tests, run the following command:\n\n```bash\nbun run test\n```\n\nFor now there are only tests in the `server` app, so you can also run them directly from the `server` app:\n\n```bash\ncd apps/server\nbun run test\n```\n\n# FAQ/Pointers\n\n## Why is relay.config.json at the root?\n\nI couldn't get the VS Code extension to work with the `relay.config.json` file in the `apps/web` directory. This also means that the relay-compiler is run from the root directory, hence why the `relay` script in `apps/web` is `cd ../.. \u0026\u0026 relay-compiler`.\n\n## Don't destructure objects, except with React hooks\n\nI've found that destructuring objects can make it harder to read and refactor code. This does not apply to destructuring arrays. Example:\n\n```js\n// ❌ Bad\nconst MyComponent = ({ value }) =\u003e {\n  return \u003cdiv\u003e{value}\u003c/div\u003e;\n};\n\n// ❌ Bad\nconst MyComponent = (props) =\u003e {\n  const { value } = props;\n  return \u003cdiv\u003e{value}\u003c/div\u003e;\n};\n\n// ✅ Good\nconst MyComponent = (props) =\u003e {\n  // destructuring objects returned by React hooks is fine\n  const { symbol } = useLocaleCurrency();\n  return \u003cdiv\u003e{props.myProp} {symbol}\u003c/div\u003e;\n};\n\n// ✅ Good\nconst MyComponent = (props) =\u003e {\n  // destructuring arrays is fine\n  const [value, setValue] = useState(props.value);\n  return \u003cdiv\u003e{value}\u003c/div\u003e;\n};\n```\n\n## Why UnoCSS instead of TailwindCSS?\n\nI was originally using TailwindCSS, but as I later realized I wanted/needed plugins to also have access to the same theme as the main app, I decided to switch to UnoCSS. This is because UnoCSS can be run at runtime, so plugins can add classes that the main app may not use directly, but that plugins can use. This is not possible with TailwindCSS, as it needs to be compiled at build time so all classes would need to be known at build time (not possible if hot swapping plugins).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichardguerre%2Fflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frichardguerre%2Fflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichardguerre%2Fflow/lists"}