Pathfinders

A canvas for branching ideas

A canvas where a single prompt branches into paths you can follow, merge, and prune, so nothing gets lost in a chat log.

---

About Pathfinders

Traditional AI chats organize ideas in one long, linear conversation. As conversations grow, useful ideas become buried, abandoned branches are difficult to revisit, and users can lose track of why they made certain decisions.

Pathfinders replaces the linear chat log with an interactive visual canvas. A single prompt can branch into multiple directions, allowing users to explore alternatives without losing earlier ideas.

The application is useful for anyone, but specifically people who struggle with brainstorming such as developing the next Notion to someone choosing a birthday gift.

Core Features

• Generate new ideas with an AI model
• Display ideas as connected nodes on a visual canvas
• Create multiple branches from any previous idea
• Continue exploring any existing branch
• Return to earlier ideas without losing progress
• Prune branches that are no longer useful
• Preserve the context and history of each branch
• Save and reopen brainstorming sessions
• Track ideas the user accepts, rejects, or ignores
• Merge related branches into a shared direction

Branch merging is a stretch goal and may be postponed to prioritize the core branching experience.

Example

A user could begin with the following prompt:

An app for my CSC 3100 class

Pathfinders might generate several possible directions:

├── Productivity tracker
├── Terminal for developers
├── Beginner-friendly context vault
└── Platform for learning how to code

Instead of choosing one direction and losing the others, the user can select any branch, develop it further, and return to the original alternatives later.

Technology Stack

Technology	Purpose
Next.js	Full-stack application framework
React	Component-based user interface
React Flow	Interactive node and branching canvas
Supabase	PostgreSQL database, authentication, and row-level security
Vercel	Application deployment and hosting
Server-side LLM API	AI-powered branch generation

System Design

Browser
  ├── React Flow canvas
  └── Supabase Auth ─────────► guest, email or Google sign-in, session cookie
        │
        ▼  requests carry the session cookie
Next.js server (route handlers, server actions)
  ├── Context assembly ──────► Groq LLM API
  └── Data access layer (lib/graph-data.js)
        │
        ▼
Supabase PostgreSQL ── RLS checks every row

Model requests are sent through the server so that the LLM API key is never exposed to the browser.

Sign-in, and moving a guest's work into an account, are described in docs/auth.md.

Context assembly is kept separate from the visual canvas. This allows the team to test and improve the information sent to the model without rewriting the user interface.

Project Structure

.
├── app/                  # Next.js pages, layouts, and server routes
├── components/           # Reusable React components
├── lib/                  # Supabase, AI, and utility functions
├── public/               # Images and other static assets
├── .env.example          # Required environment variables
├── package.json          # Dependencies and project scripts
└── README.md             # Project documentation

The directory structure may change as development continues.

Getting Started

Prerequisites

Before running Pathfinders, install:

• Git
• Node.js
• npm

You will also need access to the team's hosted Supabase project and LLM API provider. Development runs against the hosted project, so Docker is not needed.

Installation

1. Clone the repository:

   git clone https://github.com/ino464/csc-3100-software-engineering-project.git

2. Enter the project directory:

   cd csc-3100-software-engineering-project

3. Install the dependencies:

   npm install

4. Create the frontend environment file:

   cp packages/frontend/.env.example packages/frontend/.env.local

5. Fill in packages/frontend/.env.local from the hosted project's dashboard. Set NEXT_PUBLIC_SUPABASE_URL to https://<project-ref>.supabase.co, and copy the publishable key as NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY and the secret key as SUPABASE_SECRET_KEY from Project Settings, API Keys. Only the server uses the secret key, to move a guest's work into an account. Add the LLM key as GROQ_API_KEY.

6. Start the development server:

   npm run dev -w frontend

7. Open http://localhost:3000 in your browser. Without a session you are sent to /login. Choose Continue with Google, sign in or create an account with email, or continue as a guest, and you land on the session graph at /.

Everything you create in development is stored in the hosted database, which you can browse in the dashboard's Table Editor.

Working with the database

The schema lives in supabase/migrations and is never edited through the dashboard. When supabase/migrations changes, apply the new migrations to the hosted project:

npx supabase login
npx supabase link --project-ref <project-ref>
npx supabase db push

The project ref is the id in the hosted project's dashboard URL. You only need login and link once.

Optional: local Supabase stack

To test a migration without touching the hosted database, you can run a local copy of Supabase in Docker Desktop:

1. Start Docker Desktop, then run npx supabase start. The first run downloads the images and applies every migration.
2. Run npx supabase status and put its API URL (such as http://127.0.0.1:54321), publishable key and secret key in packages/frontend/.env.local in place of the hosted values.
3. After pulling a change to supabase/migrations, run npx supabase db reset, which deletes local data. After a change to supabase/config.toml, run npx supabase stop and then npx supabase start.

For Google sign-in on the local stack, put the Google client secret in supabase/.env as SUPABASE_AUTH_EXTERNAL_GOOGLE_SECRET and restart Supabase. See docs/auth.md. Local Supabase Studio runs at http://127.0.0.1:54323.

Switch .env.local back to the hosted values when you are done.

Environment Configuration

The required environment variables are documented in packages/frontend/.env.example.

# Copy the variable names from .env.example and provide your local values.

Do not commit packages/frontend/.env.local or any real API keys to the repository.

The LLM API key and SUPABASE_SECRET_KEY must only be accessed through server-side code. They should never be included in a client component or sent to the browser.

Development Commands

Command	Description
npm run dev -w frontend	Starts the development server
npm run build -w frontend	Creates a production build
npm run lint	Checks the project with ESLint
npm run format:check	Checks code formatting
npm run format	Fixes code formatting
npx supabase db push	Applies migrations to hosted
npx supabase start	Starts the optional local stack
npx supabase stop	Stops the optional local stack
npx supabase db reset	Rebuilds the local database

Continuous Integration

GitHub Actions will run automated checks on every pull request.

The initial CI workflow will verify:

• ESLint passes
• Prettier formatting is correct
• The application builds successfully

Once the workflow is added, its status badge can be placed at the top of this README.

Project Status

Pathfinders is currently in Sprint 1.

Sprint 1 Objectives

• Create the Supabase project and invite team members
• Provision an LLM API key
• Create the Vercel project and invite team members
• Create .env.example
• Create the initial project README
• Complete the Software Requirements Document
• Scaffold the frontend with Next.js
• Scaffold the backend around Supabase
• Configure CI with ESLint and Prettier

Update these checkboxes as tasks are completed:

• [ ] means incomplete
• [x] means complete

Risks and Mitigations

Risk	Mitigation
Model usage could become expensive or be abused on a public deployment	Set an account spending limit and rate-limit each session
Branch quality depends on the context sent to the model	Implement context assembly as an independently testable pure function
The visual canvas may be difficult to implement	Use React Flow and postpone branch merging if necessary
Other branching chat applications already exist	Focus on the graph, branch history, and revisiting decisions rather than recreating a normal chat interface

Team

Team Member	Role
Cole Edmonston	Lead Engineer
Ethan Ikenaga	Product Owner
Jonah Depaz	Scrum Master
Tyler Kim	Tester

Contributing

1. Create a branch for your assigned issue.
2. Make and test your changes locally.
3. Run the linting and formatting checks.
4. Push the branch to GitHub.
5. Open a pull request.
6. Request a review from another team member.

Before opening a pull request, make sure:

• The application runs locally
• No API keys or .env.local files are included
• ESLint and Prettier checks pass
• The pull request clearly explains the changes

Academic Context

Pathfinders is being developed for CSC 3100: Software Engineering at California Polytechnic State University, San Luis Obispo.

---

Developed by the Pathfinders team.