⚡ Flow

AI-native task management from natural language

Flow is a full-stack AI task management workspace that turns natural-language instructions into structured, actionable work.

Instead of manually creating tasks, setting priorities, and entering deadlines, users can interact with a single AI agent:

"Finish the backend by Friday and ask Rahul to review it tomorrow."

Flow extracts the actionable work, resolves deadlines into structured dates, persists the tasks, and immediately reflects them on a Kanban board.

The same agent can also answer questions about existing work:

"What are my high-priority tasks?"

The goal is to explore what a task-management system looks like when natural language becomes the primary interface for managing state.

Product

Flow provides a focused workspace built around two core surfaces:

AI Agent — the primary interface for creating and querying tasks.
Kanban Board — the persistent visual representation of task state.

AI Agent

The user doesn't need to switch between a task form and a chatbot.

The same agent handles both:

Create work

"Finish the backend by Friday"
                ↓
        Task is created
                ↓
       Appears in Kanban


Understand work

"What do I need to finish?"
                ↓
      Agent reads task state
                ↓
           Answers

Kanban

Tasks move through three states:

TODO  →  IN PROGRESS  →  DONE

Tasks can be dragged between columns, with the updated state persisted to PostgreSQL through the backend.

Deadline Awareness

Natural-language deadlines are converted into structured dates.

For example:

"today"
"tomorrow"
"Friday"
"next Monday"

become:

YYYY-MM-DD

The UI then derives deadline state:

Overdue
Due today
Due tomorrow
Upcoming

This allows deadlines to influence the visual state of the task rather than simply appearing as static text.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         USER                                │
│                                                             │
│  "Finish backend by Friday"                                 │
│  "What do I need to finish?"                                │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                    REACT FRONTEND                           │
│                                                             │
│  ┌─────────────────────┐        ┌────────────────────────┐  │
│  │     Flow AI         │        │     Kanban Board       │  │
│  │                     │        │                        │  │
│  │ Natural-language    │        │ TODO                   │  │
│  │ task interaction    │        │ IN PROGRESS            │  │
│  │                     │        │ DONE                   │  │
│  └──────────┬──────────┘        └────────────┬───────────┘  │
│             │                                │              │
└─────────────┼────────────────────────────────┼──────────────┘
              │ HTTP                           │ HTTP
              ▼                                ▼
┌─────────────────────────────────────────────────────────────┐
│                    FASTAPI BACKEND                           │
│                                                             │
│  /chat                 /tasks              /tasks/{id}      │
│    │                      │                    │             │
│    └──────────────┬───────┴────────────────────┘             │
│                   │                                         │
│                   ▼                                         │
│             Agent / Task Logic                              │
└──────────────┬──────────────────────────────┬───────────────┘
               │                              │
               │ AI inference                 │ Persistence
               ▼                              ▼
┌─────────────────────────┐       ┌───────────────────────────┐
│       GEMINI            │       │       SUPABASE            │
│                         │       │                           │
│ • Task extraction       │       │ PostgreSQL                │
│ • Intent classification │       │                           │
│ • Deadline resolution   │       │ tasks                     │
│ • Task-aware answers    │       │ ├── title                │
│                         │       │ ├── priority              │
└─────────────────────────┘       │ ├── due_date              │
                                  │ ├── status                 │
                                  │ └── created_at             │
                                  └───────────────────────────┘

Request Flow

1. Creating a task

A natural-language request enters through the AI interface:

"Finish the backend by Friday"

The request is sent to:

POST /chat

The backend provides the current task context to the AI agent.

The agent determines that the request represents a task creation operation and extracts:

title
priority
due_date

For example:

{
  "title": "Finish the backend",
  "priority": "medium",
  "due_date": "2026-09-25"
}

The backend persists the task in PostgreSQL through Supabase.

The frontend receives the successful response and refreshes the Kanban board.

User
  ↓
React
  ↓
POST /chat
  ↓
FastAPI
  ↓
Gemini
  ↓
Structured task
  ↓
Supabase / PostgreSQL
  ↓
React refresh
  ↓
Kanban

2. Asking about existing work

For a query such as:

"What are my high priority tasks?"

the backend retrieves the user's current tasks and provides them as context to the AI.

The agent generates an answer based on the available task state.

User question
     ↓
React
     ↓
POST /chat
     ↓
FastAPI
     ↓
Fetch current tasks
     ↓
Gemini
     ↓
Answer
     ↓
React

3. Updating task state

Dragging a task between Kanban columns triggers:

PATCH /tasks/{task_id}

with a new status:

{
  "status": "in_progress"
}

The backend updates PostgreSQL and the frontend refreshes its task state.

Technology Stack

Layer	Technology	Responsibility
Frontend	React	Application UI and state
Build Tool	Vite	Frontend development/build
Styling	Tailwind CSS	UI and responsive styling
Backend	FastAPI	API layer and application logic
Language	Python	Backend implementation
AI	Google Gemini	Natural-language understanding
Database	PostgreSQL	Persistent task state
Backend Platform	Supabase	Hosted PostgreSQL and database access

Project Structure

flow/
│
├── backend/
│   ├── main.py
│   ├── ai.py
│   ├── test_ai.py
│   ├── .env                 # local only — not committed
│   └── venv/                # local only — not committed
│
├── frontend/
│   ├── public/
│   ├── src/
│   │   ├── App.jsx
│   │   ├── App.css
│   │   ├── index.css
│   │   └── main.jsx
│   ├── package.json
│   ├── package-lock.json
│   └── vite.config.js
│
├── screenshots/
│   ├── dashboard.png
│   ├── ai-agent.png
│   └── deadlines.png
│
├── .gitignore
├── LICENSE
└── README.md

Database Model

The current application uses a tasks table in PostgreSQL.

tasks
│
├── id
├── title
├── priority
├── due_date
├── status
└── created_at

Status

todo
in_progress
done

Priority

low
medium
high

The database is intentionally simple in V1. The application treats the database as the source of truth for task state.

API

The backend currently exposes the following core endpoints.

Health check

GET /

Get tasks

GET /tasks

Returns the current task collection.

Create task

POST /tasks

Example:

{
  "title": "Finish backend",
  "priority": "high",
  "due_date": "2026-09-25"
}

AI agent

POST /chat

Example:

{
  "message": "Finish the backend by Friday"
}

The endpoint can either:

answer a task-related question, or
identify and create a new task.

Update task status

PATCH /tasks/{task_id}

Example:

{
  "status": "done"
}

Screenshots

Dashboard

The main workspace combines the Kanban board with the AI agent in a single interface.

AI Agent

The AI agent acts as the primary interface for both creating tasks and querying existing work.

Deadline Awareness

Tasks are visually differentiated based on whether their deadlines are overdue, due today, due tomorrow, or further in the future.

Running Locally

Prerequisites

Make sure you have:

Python 3
Node.js
npm
A Supabase project
A Google Gemini API key

Backend

From the repository root:

cd backend

Create a virtual environment:

python3 -m venv venv

Activate it:

macOS / Linux

source venv/bin/activate

Install dependencies:

pip install fastapi uvicorn python-dotenv supabase google-genai pydantic

Create:

backend/.env

with your own credentials:

SUPABASE_URL=your_supabase_url
SUPABASE_SECRET_KEY=your_supabase_secret
GEMINI_API_KEY=your_gemini_api_key

Never commit .env or expose these credentials publicly.

Start the API:

uvicorn main:app --reload

The backend will be available at:

http://127.0.0.1:8000

Interactive API documentation is available at:

http://127.0.0.1:8000/docs

Frontend

Open another terminal:

cd frontend

Install dependencies:

npm install

Start the development server:

npm run dev

Open:

http://localhost:5173

Configuration

The backend expects these environment variables:

SUPABASE_URL
SUPABASE_SECRET_KEY
GEMINI_API_KEY

The real .env file is excluded from Git using .gitignore.

Design Decisions

Natural language as the primary interface

Traditional task applications make users manually specify:

Title
Priority
Deadline
Status

Flow explores a different interaction model.

The user expresses intent naturally and the system converts that intent into structured application state.

This makes the AI layer responsible for understanding the request while the database remains responsible for maintaining deterministic state.

AI does not own application state

The AI interprets natural language, but task state is persisted in PostgreSQL.

Conceptually:

AI
 ↓
understands intent
 ↓
structured operation
 ↓
Database
 ↓
source of truth

This separation is important because the model should not be treated as the persistent state of the application.

Structured dates

Early versions of the application represented deadlines as strings such as:

"Friday"
"Tomorrow"
"Monday"

That made reliable deadline reasoning difficult.

The current implementation stores:

YYYY-MM-DD

and derives states such as overdue/today/tomorrow in the application layer.

This allows the UI to reason deterministically about deadlines rather than relying on another LLM interpretation.

Current Limitations

Flow is currently a focused V1 rather than a production-ready multi-user system.

Some areas intentionally remain outside the current implementation:

Authentication
Multi-user isolation
Slack/WhatsApp integrations
Background job processing
Task history/event sourcing
Semantic retrieval
Calendar synchronization
Advanced agent tool calling
Production deployment
Rate limiting
Comprehensive automated test coverage

These are potential directions for future iterations.

Roadmap

V1 — Current

V2 — Potential

V3 — Potential

Engineering Direction

The longer-term direction for Flow is to move from a simple AI task extractor toward an AI-native state management system.

Instead of treating the LLM as a chatbot sitting beside a traditional application, the goal is to let natural language operate on structured application state through explicit tools and well-defined backend operations.

A future interaction could look like:

"Move the backend task to in progress,
tell Rahul I need his review,
and remind me tomorrow if it isn't done."

The agent could decompose that request into multiple validated operations:

        Natural Language
               │
               ▼
        Agent / Planner
               │
       ┌───────┼────────┐
       ▼       ▼        ▼
   Update    Message   Reminder
    Task      Action    Action
       │       │        │
       └───────┼────────┘
               ▼
        Application State

That architecture is deliberately not part of the current V1; it represents the direction in which the system can evolve.

License

MIT License.

Latest commit

History

Folders and files

Repository files navigation

⚡ Flow

AI-native task management from natural language

Product

AI Agent

Kanban

Deadline Awareness

Architecture

Request Flow

1. Creating a task

2. Asking about existing work

3. Updating task state

Technology Stack

Project Structure

Database Model

Status

Priority

API

Health check

Get tasks

Create task

AI agent

Update task status

Screenshots

Dashboard

AI Agent

Deadline Awareness

Running Locally

Prerequisites

Backend

macOS / Linux

Frontend

Configuration

Design Decisions

Natural language as the primary interface

AI does not own application state

Structured dates

Current Limitations

Roadmap

V1 — Current

V2 — Potential

V3 — Potential

Engineering Direction

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages