Architecture

Tech Stack

Authentication

Hierarch uses Supabase Auth for user authentication. Two methods are supported: email/password signup and Google OAuth. Session state is managed entirely by the Supabase client library, which persists tokens in the browser and handles automatic refresh.

On login, the app listens to onAuthStateChange from the Supabase client. When a valid session is detected, the app transitions to the authenticated state and begins loading user data.

Third-party integrations (Linear, Figma, Jira, Slack) authenticate via OAuth 2.0. Tokens are exchanged through Vercel serverless functions and stored server-side in Supabase, associated with the authenticated user. See each integration's documentation for specific OAuth scopes and flows.

Environment Variables

Database Schema

Hierarch uses three primary tables in Supabase Postgres. All tables enforce row-level security (RLS) where owner_id = auth.uid() for every operation.

projects

id           uuid        PRIMARY KEY
owner_id     uuid        REFERENCES auth.users
name         text
description  text
metadata     jsonb       — icon, color, type, order, blockers,
                           start_date, end_date
created_at   timestamptz
start_date   text        — ISO date string
end_date     text        — ISO date string

tasks

id           uuid        PRIMARY KEY
owner_id     uuid        REFERENCES auth.users
project_id   uuid        REFERENCES projects (nullable)
title        text
description  text        — JSON: { content, phaseHistory[] }
status       text        — explore | design | iterate | review | handoff
due_at       timestamptz — stored as local time 'yyyy-MM-ddTHH:mm'
position     int
created_at   timestamptz

The description column stores a JSON object containing the task's rich text content and the complete phase transition history.

task_blockers

id           uuid        PRIMARY KEY
owner_id     uuid        REFERENCES auth.users
task_id      uuid        REFERENCES tasks (CASCADE on delete)
text         text
type         text        — person | team | external | task
done         boolean     DEFAULT false
created_at   timestamptz

Blockers are stored in a dedicated table with row-level security enforcing owner_id = auth.uid(). Each blocker has a typed category (person, team, external, or task dependency) and a resolved state. Blocked tasks display a lock icon in list and board views.

resources

id           uuid        PRIMARY KEY
owner_id     uuid        REFERENCES auth.users
project_id   uuid        REFERENCES projects (nullable)
task_id      uuid        REFERENCES tasks (SET NULL on delete)
type         text        — Project Note | Meeting Note | Research | Link
title        text
content      text        — JSON: { content, pinned, order, metadata }
created_at   timestamptz

Cascade Behavior

• Deleting a project cascades to all its tasks and resources.
• Deleting a task sets task_id to null on any linked resources (they become unlinked, preserved for reference).

State Management

All application state lives as useState hooks in the root component. This includes auth state, projects, tasks, artifacts, time entries, the selected item, and the drawer navigation stack.

Views are driven by an activeView string (e.g. "today", "all", "linear"). The sidebar sets this string, and the main content area renders the corresponding component.

Edge Functions

Hierarch runs a small set of serverless edge functions on Supabase using the Hono framework (Deno runtime). These handle operations that require admin-level access or server-side processing. See the API Reference for full endpoint documentation.

Deployment

The frontend deploys to Vercel. Edge functions deploy to Supabase independently. The Supabase project handles database migrations, auth configuration, and storage bucket management.