The GitHub OAuth and Repository Sync system is a core integration feature of the Colabs platform. It allows users to link their GitHub accounts to the platform, enabling the synchronization of personal or organization repositories. This integration serves as the foundation for features such as issue claiming and project collaboration tracking.

The system is architected as a decoupled integration flow, distinct from the primary authentication flow. While users sign in to Colabs via Supabase Auth, the GitHub integration specifically requests repo and user:email scopes to interact with the GitHub API on behalf of the user. Once connected, the system periodically fetches and caches repository metadata in the Supabase database.

Sources: CLAUDE.md:129-140, src/hooks/useGitHub.tsx:43-45

The integration uses a standard OAuth 2.0 Authorization Code Grant flow. The process begins on the client side, redirects to GitHub for authorization, and handles the exchange of an authorization code for an access token within a secure Supabase Edge Function.

1. Initiation: The user clicks "Connect GitHub Account" in the GitHubIntegration component.
2. Redirect: The useGitHub hook generates a unique state for CSRF protection, stores it in localStorage, and redirects the user to GitHub.
3. Callback: After the user approves, GitHub redirects back to /github-callback with a code and state.
4. Exchange: The client sends the code to the github-oauth Edge Function.
5. Token Storage: The Edge Function exchanges the code for a GitHub access token and stores it in a secure, non-client-accessible table.

Sources: src/hooks/useGitHub.tsx:37-60, supabase/functions/github-oauth/index.ts:25-50

The following diagram illustrates the interaction between the React frontend, GitHub API, and Supabase Edge Functions during the OAuth handshake.

sequenceDiagram
    participant User as User Browser
    participant App as Colabs Frontend
    participant GH as GitHub API
    participant EF as Supabase Edge Function
    participant DB as PostgreSQL (Supabase)

    User->>App: Click "Connect GitHub"
    App->>App: Generate & Store state
    App->>GH: Redirect to /login/oauth/authorize
    GH->>User: Prompt for permissions
    User->>GH: Authorize App
    GH->>App: Redirect to /github-callback?code=XYZ
    App->>EF: Invoke github-oauth {code, state}
    EF->>GH: POST /login/oauth/access_token
    GH-->>EF: Return access_token
    EF->>GH: GET /user (Profile data)
    GH-->>EF: Return GitHub Profile
    EF->>DB: Upsert github_integrations
    EF->>DB: Upsert github_integration_secrets
    EF-->>App: Return success & integration metadata
    App->>App: Invoke syncRepositories()

Sources: src/hooks/useGitHub.tsx:84-110, supabase/functions/github-oauth/index.ts:25-104

Once the integration is active, the system provides a synchronization mechanism to fetch the user's repositories and store them locally in the github_repositories table.

The github-repositories Edge Function performs the following actions during a GET request:

1. Retrieves the stored access_token from github_integration_secrets using the Supabase Service Role key.
2. Requests the user's repository list from https://api.github.com/user/repos.
3. Maps GitHub API response fields to the internal schema.
4. Performs an upsert operation on the github_repositories table, keyed by integration_id and github_repo_id.

Sources: supabase/functions/github-repositories/index.ts:44-90, src/hooks/useGitHub.tsx:64-82

Sources: src/hooks/useGitHub.tsx:29-35, supabase/functions/github-oauth/index.ts:88-104, CLAUDE.md:323-332

Users can toggle "Collaboration" on specific repositories. This flag determines which repositories are visible to other contributors on the platform for issue claiming.

The system tracks several fields for each synced repository:

• Identification: github_repo_id, name, full_name.
• Stats: stars_count, forks_count.
• Settings: allow_collaboration (boolean), visibility (public/private).
• Metadata: language, topics, description, html_url.

Sources: supabase/functions/github-repositories/index.ts:93-110, src/hooks/useGitHub.tsx:13-26

When a user toggles the collaboration switch in the UI:

1. The updateRepositoryCollaboration function in useGitHub.tsx is called.
2. A POST request is sent to the github-repositories Edge Function.
3. The Edge Function updates the allow_collaboration and updated_at columns in the database.

Sources: src/components/GitHubIntegration.tsx:49-51, src/hooks/useGitHub.tsx:120-150, supabase/functions/github-repositories/index.ts:133-157

The system adheres to strict security protocols regarding the handling of GitHub credentials.

GitHub access_token values are never stored in the main github_integrations table. Instead, they are kept in github_integration_secrets. This isolation ensures that even if a client-side query fetches integration metadata, the sensitive token remains protected because no RLS policies allow client access to the secrets table.

Sources: CLAUDE.md:323-335, supabase/functions/github-oauth/index.ts:107-112

Every Edge Function verifying GitHub data performs the following:

1. JWT Verification: Uses supabase.auth.getUser(token) to ensure the requester is a valid Colabs user.
2. Service Role Access: Uses the SUPABASE_SERVICE_ROLE_KEY to read from the secrets table, bypassing RLS internally within the secure Deno environment.
3. CORS Handling: Implements preflight OPTIONS responses with restricted headers.

Sources: supabase/functions/github-oauth/index.ts:15-18, 71-82, supabase/functions/github-repositories/index.ts:25-40

The GitHub OAuth and Repository Sync system provides a secure bridge between a developer's GitHub activity and the Colabs platform. By leveraging Supabase Edge Functions and isolated secret storage, it ensures that repository metadata can be synchronized and managed for collaboration without exposing user credentials to the frontend. This system enables the platform to provide live updates on repository statistics and open issues to the community.

The Gig Marketplace Engine is a core functional module of the Colabs platform designed to connect project owners (clients) with independent developers through a structured freelance ecosystem. It facilitates the entire lifecycle of a freelance engagement, from gig creation and discovery to proposal submission and management. The engine leverages Supabase for real-time data persistence and TanStack Query for efficient client-side state management.

The engine integrates closely with the broader Project Discovery and Contributor Analytics systems, allowing users to leverage their GitHub-backed profiles when applying for paid opportunities. It supports features such as milestone-based budgeting, urgent project tagging, and role-based dashboards for both sellers and applicants. Sources: README.md:38-40, CLAUDE.md:14-17

The marketplace is built upon a robust PostgreSQL schema managed via Supabase. The primary entity is the gigs table, which stores detailed metadata about the work opportunity, the client, and the required technical stack.

The following table describes the primary data structure for gigs:

Sources: src/hooks/useGigs.tsx:6-33, supabase/migrations/20260308134958_59b5c7ec-ca44-46df-a9cd-5b2aad69b89d.sql:3-4

This diagram illustrates the flow of data from gig creation through to the marketplace discovery.

graph TD
    User[Client User] -->|Form Input| Dialog[CreateGigDialog]
    Dialog -->|Validation| Zod[Zod Schema]
    Zod -->|Insert/Update| Supabase[(Supabase DB)]
    Supabase -->|Query Hook| useGigs[useGigs Hook]
    useGigs -->|Filtered Data| Marketplace[Marketplace UI]
    Marketplace -->|Details| GigDetails[GigDetails Page]

Sources: src/components/CreateGigDialog.tsx:30-149, src/hooks/useGigs.tsx:65-76

The engine provides a comprehensive interface for clients to define work opportunities. The CreateGigDialog component handles validation and submission of new listings.

The system uses Zod for strict client-side validation, ensuring that critical fields like title, company, and budget meet length and format requirements.

• Requirements & Deliverables: Stored as arrays of strings to provide structured lists in the UI.
• Classification: Gigs are categorized by industry (e.g., Web Development, DevOps) and difficulty level.
• Urgency: Clients can toggle an isUrgent flag to increase visibility.

Sources: src/components/CreateGigDialog.tsx:30-58, src/components/CreateGigDialog.tsx:162-176

The SellerDashboard allows clients to manage their active listings.

sequenceDiagram
    participant Seller as Seller Dashboard
    participant API as Supabase Client
    participant Cache as React Query Cache

    Seller->>API: toggleStatus(gigId, 'paused')
    API-->>Seller: Success Response
    Seller->>Cache: invalidateQueries(['gigs'])
    Cache-->>Seller: UI Re-renders with updated status

Sources: src/pages/SellerDashboard.tsx:112-121, src/pages/SellerDashboard.tsx:135-144

The engine includes a specialized proposal workflow (SubmitProposal.tsx) that allows developers to bid on gigs using either fixed-price or hourly models.

For fixed-price contracts, the engine supports a milestone structure where the total project cost is aggregated from individual deliverables.

flowchart TD
    Start[Start Proposal] --> SelectType{Payment Type}
    SelectType -->|Fixed| Milestones[Add Milestones]
    SelectType -->|Hourly| Rate[Set Hourly Rate]
    Milestones --> Calc[Calculate Total Amount]
    Rate --> Calc
    Calc --> Files[Attach Resume/GitHub]
    Files --> Submit[Submit to Supabase]

Sources: src/pages/SubmitProposal.tsx:32-49, src/pages/SubmitProposal.tsx:61-64

Sources: src/pages/SubmitProposal.tsx:142-184, src/pages/SubmitProposal.tsx:111-118

Discovery is handled by the useGigs hook, which provides various fetching patterns for different UI contexts.

1. useGigs(): Fetches all active gigs for the public marketplace, ordered by recency.
2. useMyGigs(userId): Filters gigs created by a specific client for their dashboard.
3. useGigById(id): Retrieves full details for a single gig, including client metrics (hire rate, total spent).

Sources: src/hooks/useGigs.tsx:65-103

The GigsTab component implements sophisticated client-side filtering and sorting for users managing their applications.

• Sort Fields: Budget, Date Posted, Title, and Status.
• Status Grouping: Applications are grouped into applied, interviewing, accepted, and rejected.
• Search: Real-time search across titles, companies, and technologies.

Sources: src/components/dashboard/GigsTab.tsx:300-335, src/components/dashboard/GigsTab.tsx:343-348

The Gig Marketplace Engine serves as the transactional heart of Colabs. By combining a flexible PostgreSQL schema with real-time updates and structured proposal workflows, it provides a professional environment for freelance collaboration. The system's reliance on validated data and milestone-based payments ensures transparency and security for both clients and developers.

Project Discovery & Explorer is a core module of the Colabs platform designed to connect developers with open-source and collaborative projects. It provides a structured interface for browsing, filtering, and deep-diving into project details, including technical stacks, live GitHub statistics, and contribution opportunities. Sources: README.md, CLAUDE.md:14-18

The system serves multiple personas: developers looking for projects matching their skills, project owners seeking contributors, and team leads managing shared workspaces. It bridges the gap between high-level project exploration and granular technical contribution by integrating directly with the GitHub API for real-time data sync. Sources: README.md, src/pages/Project.tsx:112-127

The Discovery module follows a decentralized data fetching pattern where individual pages and container components own the data lifecycle, while presentational components render the state. Sources: CLAUDE.md:144-146

Project data is retrieved from Supabase (PostgreSQL) and augmented with live data from the GitHub API via Supabase Edge Functions.

sequenceDiagram
    participant User as "User Interface"
    participant DB as "Supabase DB"
    participant Edge as "Edge Function"
    participant GH as "GitHub API"

    User->>DB: SELECT * FROM projects WHERE id = :id
    DB-->>User: Project Metadata
    Note over User: Check for github_repo_url
    User->>Edge: invoke('github-project-data', { repoUrl })
    Edge->>GH: Fetch Stars, Issues, Contributors
    GH-->>Edge: JSON Data
    Edge-->>User: Unified GitHub Stats
    User->>User: Render Project Dashboard

Sources: src/pages/Project.tsx:94-110, src/pages/Project.tsx:112-127, CLAUDE.md:175-182

The explorer utilizes several viewing components depending on the context (e.g., landing page vs. dedicated explorer page):

Projects are managed via the CreateProjectDialog, which uses a multi-step form to collect metadata, technical requirements, and external tool integrations. Sources: src/components/CreateProjectDialog.tsx:73-78

flowchart TD
    Start[Open Dialog] --> Step1[Basics: Name & Desc]
    Step1 --> Step2[Details: Type & Compensation]
    Step2 --> Step3[Links: GitHub & Tools]
    Step3 --> Step4[Settings: Visibility & Invites]
    Step4 --> Submit[Save to Supabase]
    
    subgraph Validation
    Step1 -- Required check --> Step1
    end

Sources: src/components/CreateProjectDialog.tsx:327-580

The discovery engine relies on a comprehensive project schema that tracks both metadata and collaboration settings.

Sources: src/pages/Project.tsx:30-55, src/components/CreateProjectDialog.tsx:18-40

When a github_repo_url is provided, the Discovery module invokes the github-project-data edge function. This provides:

• Repo Stats: Stars, Forks, Watchers, and License information. Sources: src/pages/Project.tsx:190-210
• Contributors: A list of GitHub users with contribution counts and avatars. Sources: src/pages/Project.tsx:334-360
• Open Issues: Live issue tracking, including "Good First Issue" badges to encourage new contributors. Sources: src/pages/Project.tsx:365-416

// Edge function invocation for GitHub data
const { data, error } = await supabase.functions.invoke('github-project-data', {
  body: { repoUrl: project.github_repo_url },
});

Sources: src/pages/Project.tsx:117-120

The Explorer implements client-side filtering and recommendation systems:

• Skill Matching: Projects are recommended to users in the IssuesTab based on their "tech stack and interests." Sources: src/components/dashboard/IssuesTab.tsx:768-771
• Complexity Levels: Projects and issues are categorized by difficulty (e.g., "Beginner", "Expert") and color-coded (Green for Beginner, Red for Advanced). Sources: src/components/ProjectsSection.tsx:83-93, src/components/dashboard/IssuesTab.tsx:129-144

The Project Discovery & Explorer module is the central hub for collaboration within Colabs. By combining static metadata from Supabase with live signals from GitHub, it provides a high-fidelity view of the open-source ecosystem, enabling developers to find opportunities that match their specific technical skills and career goals. Sources: README.md, src/pages/Project.tsx

The Issue Claiming and Kanban Board system in Colabs enables developers to discover open GitHub issues, "claim" them for their personal workflow, and track their progress through a structured status lifecycle. This system bridges external GitHub repository activity with the platform's internal contribution tracking, providing a unified interface for managing open-source tasks.

Developers can browse issues across all collaboration-enabled repositories, view detailed metadata through a side panel, and transition claimed issues through a Kanban board featuring drag-and-drop functionality. This workflow is powered by Supabase Edge Functions that sync with the GitHub API and a dedicated database table for tracking claimed items. Sources: README.md:65-67, src/components/dashboard/IssuesTab.tsx:392-411

The system consists of three primary layers: the external GitHub API, the Supabase Edge Function for data fetching, and the React frontend components for visualization and interaction.

1. The frontend invokes the github-issues Edge Function.
2. The Edge Function verifies the user's JWT and retrieves their GitHub access token.
3. It identifies repositories where allow_collaboration is true.
4. It fetches open issues from GitHub, transforms them into a unified format, and filters out Pull Requests.
5. The frontend displays these issues in the "Explore Issues" view.

flowchart TD
    User[User Interface] -->|Invoke| EF[github-issues Edge Function]
    EF -->|Verify| Auth[Supabase Auth]
    EF -->|Fetch Access Token| DB_Sec[github_integration_secrets]
    EF -->|Identify Repos| DB_Repo[github_repositories]
    EF -->|Request Issues| GH[GitHub API]
    GH -->|Return JSON| EF
    EF -->|Transform & Filter| User

Sources: supabase/functions/github-issues/index.ts:32-132, src/pages/AllIssues.tsx:325-330

Claiming an issue creates a persistent record in the claimed_issues table. This record snapshots the issue metadata (title, description, labels, repo info) at the time of claiming and associates it with the user's unique ID.

• useClaimedIssues Hook: Centralizes logic for fetching, inserting, updating, and deleting claimed issues. It utilizes a Set of claimedIssueIds for O(1) lookups to determine if an issue is already claimed in UI lists.

• claimIssue(issue): Performs a Supabase insert into the claimed_issues table. It includes error handling for unique constraint violations (code 23505) to prevent duplicate claims.

• unclaimIssue(issueId): Deletes the record from the database, effectively removing it from the user's dashboard. Sources: src/hooks/useClaimedIssues.tsx:43-118

The Kanban board provides a visual representation of a user's claimed issues, organized by their current status. It is implemented using @hello-pangea/dnd for fluid drag-and-drop interactions.

Issues move through a linear progression represented by columns:

1. Todo: Default state for newly claimed issues.
2. In Progress: Actively being worked on.
3. In Review: Work submitted for feedback.
4. Done: Task completed. Sources: src/components/dashboard/IssuesTab.tsx:160-185, src/components/IssuesSection.tsx:106-111

sequenceDiagram
    participant U as User
    participant K as Kanban Board
    participant H as useClaimedIssues Hook
    participant DB as Supabase Database

    U->>K: Drag Issue to "In Progress"
    K->>H: updateStatus(id, "in-progress")
    H->>DB: UPDATE claimed_issues SET status = 'in-progress'
    DB-->>H: Success
    H->>H: fetchClaimed() (Refetch)
    H-->>K: Update UI state

Sources: src/components/dashboard/IssuesTab.tsx:465-470, src/hooks/useClaimedIssues.tsx:120-137

The system utilizes several specialized components to handle different view modes and detailed interactions.

A sheet-based component that provides a deep dive into an issue's content. It supports context-aware actions:

• Claim/Unclaim: Conditional buttons based on whether the issue is already in the user's list.
• External Links: Direct navigation to GitHub, Linear, or Figma if URLs are provided in the metadata.
• Save/Bookmark: Local storage persistence for issues the user is interested in but hasn't claimed yet. Sources: src/components/issues/IssueSidePanel.tsx:68-191

The "My Issues" tab supports two primary layouts, persisted via localStorage:

• List View: A grouped list sorted by status, optimized for high-density information.
• Kanban View: A multi-column drag-and-drop interface for task management. Sources: src/components/dashboard/IssuesTab.tsx:210-220, src/components/dashboard/IssuesTab.tsx:540-562

The system maps GitHub labels and metadata to internal categories and priorities:

The Issue Claiming and Kanban system centralizes the developer experience by providing a workspace to manage external contributions. By combining real-time GitHub data sync with a persistent internal status tracker, Colabs allows contributors to maintain a clear "Todo" list and progress through tasks within a standardized agile workflow. Sources: src/components/dashboard/IssuesTab.tsx:392-411, src/hooks/useClaimedIssues.tsx:1-5

The Proposals & Applications System is a core module within the Colabs platform that facilitates formal engagement between developers and project owners. It allows users to submit structured applications for specific "gigs" or projects, detailing their technical approach, financial requirements, and professional background.

This system manages the entire lifecycle of an application—from submission and file storage (resumes) to milestone definition and status tracking. It integrates directly with Supabase for data persistence and Row Level Security (RLS) to ensure that only proposal owners and project creators can access sensitive application data.

The system is built upon two primary database tables: proposals and proposal_milestones. These tables track the core metadata of an application and the specific deliverables associated with fixed-price payment models.

Sources: supabase/migrations/20250813062113-.sql:2-22, src/integrations/supabase/types.ts:474-539

The following diagram illustrates the relationship between users, projects, proposals, and their associated milestones.

erDiagram
    PROJECT ||--o{ PROPOSAL : receives
    USER ||--o{ PROPOSAL : submits
    PROPOSAL ||--o{ PROPOSAL_MILESTONE : contains
    
    PROPOSAL {
        uuid id PK
        uuid user_id FK
        text project_id FK
        text status
        text payment_type
        int total_amount
        text total_duration
        text resume_path
        text cover_letter
        text github_url
    }

    PROPOSAL_MILESTONE {
        uuid id PK
        uuid proposal_id FK
        text title
        text duration
        int amount
        int order_index
    }

Sources: supabase/migrations/20250813062113-.sql:2-22, src/integrations/supabase/types.ts:474-539

The submission process is handled by the SubmitProposal component. It implements a multi-section form that validates user input before persisting data to Supabase and uploading files to Storage.

flowchart TD
    Start[User selects 'Submit Proposal'] --> AuthCheck{AuthGuard: User Logged In?}
    AuthCheck -- No --> SignIn[Redirect to Sign In]
    AuthCheck -- Yes --> Form[Fill Proposal Form]
    
    Form --> Valid{Validation: Required Fields?}
    Valid -- No --> Error[Show Toast Error]
    Valid -- Yes --> Upload[Upload Resume to Storage]
    
    Upload --> DB_Prop[Insert into 'proposals']
    DB_Prop --> MilestoneCheck{Payment Type: Fixed?}
    
    MilestoneCheck -- Yes --> DB_Mile[Insert into 'proposal_milestones']
    MilestoneCheck -- No --> Success[Navigate to /proposals]
    DB_Mile --> Success

Sources: src/pages/SubmitProposal.tsx:114-192, src/pages/SubmitProposal.tsx:216-410

• File Handling: Resumes are restricted to PDF, DOC, or DOCX formats with a maximum size of 5MB (validated client-side) or 10MB (validated in the submission handler). Files are stored in a private Supabase bucket named resumes using a path structured as user_id/timestamp.extension.

• Payment Types: Users choose between fixed (milestone-based) or hourly rates.

• Form Validation: Required fields include coverLetter, githubUrl, and either an hourlyRate or at least one milestone title for fixed pricing.

Sources: src/pages/SubmitProposal.tsx:132-159, src/pages/SubmitProposal.tsx:34-45, src/pages/SubmitProposal.tsx:106-112

Security is enforced at the database level using Row Level Security (RLS) policies. This ensures that sensitive information like resumes and financial bids are not exposed to unauthorized users.

Sources: supabase/migrations/20250813062113-.sql:31-70, supabase/migrations/20250813062113-.sql:82-110

Users can monitor the status of their submitted applications through the MyProposals page. This view provides a high-level summary of all applications linked to the authenticated user's ID.

Proposals transition through various states, represented by UI badges:

• submitted: The initial state upon creation.
• accepted: Displayed with the default (primary) badge variant.
• rejected: Displayed with the destructive (red) badge variant.

Sources: src/pages/MyProposals.tsx:43-52, supabase/migrations/20250813062113-.sql:13

The system fetches proposals sorted by created_at in descending order to show the most recent applications first.

const { data, error } = await supabase
  .from('proposals' as any)
  .select('id, created_at, status, payment_type, total_amount, total_duration, project_id')
  .order('created_at', { ascending: false });

Sources: src/pages/MyProposals.tsx:26-31

The proposal system is tightly coupled with the Project module. Projects can toggle whether they allow applications via the allow_applications boolean field. When a project is viewed, the ProjectPage component provides a call-to-action button that routes users to the proposal submission form using the project's unique ID.

Sources: src/pages/Project.tsx:254-258, src/pages/Project.tsx:46

The Proposals & Applications System provides a structured bridge between contributors and project owners in Colabs. By utilizing a combination of React-based forms for submission, Supabase Storage for resumes, and strict RLS policies, the system ensures a secure and efficient application process. Key features like milestone-based budgeting and status tracking allow for professional freelance-style interactions within an open-source collaboration environment.

Teams Workspace & Management is a core module within Colabs designed to facilitate structured collaboration between developers, project leads, and organization admins. It provides a unified environment where team leads can create teams, invite members via email, and manage shared workspaces for assigned projects. This system bridges the gap between raw GitHub activity and project-level management, allowing teams to track progress through integrated tasks and activity feeds.

The system is built as part of a React 18 SPA backed by Supabase, utilizing PostgreSQL for data persistence and Row Level Security (RLS) to ensure that team data remains accessible only to authorized members. It integrates with the broader Organizations and Project Management modules to provide a multi-tier hierarchy for collaboration. Sources: README.md:46-52, CLAUDE.md:14-18

The platform utilizes a hierarchical structure for access control and management, ranging from individual contributors to high-level organization owners.

Teams and Organizations operate under a role hierarchy that dictates permissions for managing settings, integrations, and member invitations.

Sources: src/pages/OrganizationDashboard.tsx:68-80, README.md:52-55

The following diagram illustrates the relationship between Organizations, Teams, Projects, and Members as derived from the component structures and database access patterns.

erDiagram
    ORGANIZATION ||--o{ TEAM : contains
    ORGANIZATION ||--o{ ORGANIZATION_MEMBER : has
    TEAM ||--o{ TEAM_MEMBER : has
    PROJECT ||--o{ TEAM : assigned_to
    TEAM_MEMBER }|--|| AUTH_USER : references
    ORGANIZATION_MEMBER }|--|| AUTH_USER : references

The system ensures data integrity using foreign key references to auth.users(id) and enforces security via RLS policies like is_team_member(auth.uid(), team_id). Sources: CLAUDE.md:126-135, src/pages/OrganizationDashboard.tsx:55-100

The Team Workspace serves as the primary operational dashboard for a specific team. It aggregates tasks, member status, and recent activity into a single view.

Tasks within the workspace are tracked via a status-based workflow (Todo, In Progress, In Review, Done, Blocked). Each task includes metadata such as assignees, estimated completion, and source references from external tools like GitHub or Figma.

Task Status Configuration:

• Todo: Initial state for new items.
• In Progress: Items currently being worked on (marked with yellow indicators).
• In Review: Items awaiting peer or lead approval (marked with blue indicators).
• Done: Successfully completed items (marked with green indicators).
• Blocked: Items hindered by external dependencies (marked with destructive red indicators).

Sources: src/components/dashboard/TeamWorkspace.tsx:162-168, src/components/dashboard/TeamWorkspace.tsx:55-68

The workspace UI is divided into a main task view and a contextual sidebar for team-wide statistics.

flowchart TD
    A[Team Workspace] --> B[Header: Stats & Nav]
    A --> C[Main Content Area]
    A --> D[Sidebar]
    C --> E[Risks & Blockers Callout]
    C --> F[Active Tasks List]
    C --> G[Completed Tasks List]
    D --> H[Member Status List]
    D --> I[Weekly Contribution Stats]
    D --> J[Real-time Activity Feed]

The TeamWorkspace component calculates overall progress by averaging the progress percentage of all tasks associated with the team. Sources: src/components/dashboard/TeamWorkspace.tsx:288-305, src/components/dashboard/TeamWorkspace.tsx:340-360

Teams often operate within the context of a larger Organization. The Organization Dashboard provides tools to oversee multiple teams and their collective output.

Organizations can connect external tools that feed data into team workspaces. Supported integrations include GitHub for repository tracking, Slack for notifications, and Figma for design updates.

sequenceDiagram
    participant Admin as "Org Admin"
    participant DB as "Supabase DB"
    participant Ext as "External API (GitHub/Slack)"
    Admin->>DB: Select Integration Type
    DB-->>Admin: Request OAuth / API Key
    Admin->>Ext: Authorize Application
    Ext-->>DB: Store Encrypted Token
    DB-->>Admin: Integration Active

Sources: src/pages/OrganizationDashboard.tsx:205-240, src/pages/Organizations.tsx:88-110

The system tracks team performance using several key metrics:

• Commits/PRs: Sourced via GitHub integration to measure code output.
• Hours Allocated: Tracked against task estimates.
• Blocked Rate: Identifies bottlenecks in the team workflow. Sources: src/components/dashboard/TeamWorkspace.tsx:141-158, src/pages/OrganizationDashboard.tsx:158-185

Team management strictly adheres to the project's RLS (Row Level Security) mental model.

1. Membership-based Access: Access to a team's workspace is gated by the is_team_member() security definer function.
2. Role-based Write Access: Only users with owner or admin roles within the parent organization can modify team settings or invite new members.
3. Token Security: Integration tokens (e.g., GitHub access tokens) are stored in separate tables with no public RLS policies, ensuring they are only accessible via Supabase Edge Functions using the service role key.

Sources: CLAUDE.md:126-135, CLAUDE.md:162-172, src/pages/OrganizationDashboard.tsx:75-80

Teams Workspace & Management provides a structured layer for collaboration within Colabs, transforming raw repository data into actionable team insights. By integrating task management, real-time activity feeds, and organization-level RBAC, the system enables efficient project execution and oversight. The module relies heavily on Supabase RLS and GitHub integration to maintain a secure and automated environment for modern development teams.

Organization Access Control in the Colabs project is a multi-tier management system designed to govern user interactions, permissions, and resource ownership within an organization. It utilizes a Role-Based Access Control (RBAC) model to ensure that users have appropriate levels of authority to manage projects, integrations, and team memberships.

The system is built on top of Supabase's Row Level Security (RLS) and PostgreSQL, where access is verified against the user's role and membership status. This architectural choice ensures that security is enforced at the database layer, preventing unauthorized data exposure even if client-side checks are bypassed.

The project defines a specific hierarchy for organization members using an enumeration type. This hierarchy determines the breadth of administrative actions a user can perform within the dashboard and across linked resources.

The system utilizes three primary roles:

• Owner: The creator of the organization. Has full authority, including deleting the organization and managing other high-level administrators.
• Admin: Has administrative privileges to manage integrations, workflows, and invite members.
• Member: Standard access level focused on collaboration and viewing organization resources.

Sources: src/integrations/supabase/types.ts:696-698, src/pages/OrganizationDashboard.tsx:84-95

The frontend implements feature gating by checking the userRole state. Certain UI elements, such as "Settings," "Add Integration," and "Invite Member," are only rendered for users with elevated privileges.

flowchart TD
    User[User Accesses Dashboard] --> FetchRole[Fetch user_role from organization_members]
    FetchRole --> CheckRole{Is Owner or Admin?}
    CheckRole -- Yes --> ShowAdminUI[Show Settings, Invite, & Add Integration Buttons]
    CheckRole -- No --> ShowMemberUI[Show Standard Overview & Member List]
    ShowAdminUI --> Action[Perform Administrative Task]

Sources: src/pages/OrganizationDashboard.tsx:165-170, src/pages/OrganizationDashboard.tsx:288-294

The access control system is supported by three primary tables in the Supabase schema: organizations, organization_members, and organization_integrations.

The following Entity-Relationship diagram illustrates how users are linked to organizations and how roles are assigned.

erDiagram
    ORGANIZATIONS ||--o{ ORGANIZATION_MEMBERS : contains
    ORGANIZATIONS ||--o{ ORGANIZATION_INTEGRATIONS : owns
    ORGANIZATION_MEMBERS }o--|| USERS : references
    
    ORGANIZATIONS {
        uuid id PK
        text name
        text slug
        uuid creator_id
    }
    
    ORGANIZATION_MEMBERS {
        uuid id PK
        uuid organization_id FK
        uuid user_id FK
        org_role role
    }

Sources: src/integrations/supabase/types.ts:413-463, src/integrations/supabase/types.ts:503-535

Sources: src/integrations/supabase/types.ts:504-510, src/integrations/supabase/types.ts:696-698

Security is enforced primarily through Supabase Row Level Security (RLS). PostgreSQL evaluates policies against auth.uid() before returning rows or allowing modifications.

The project adheres to several canonical RLS patterns to protect organization data:

1. Membership-based: Access is granted if a record exists in organization_members for the current auth.uid().
2. Role-based write: Mutations (INSERT/UPDATE/DELETE) are restricted to users where get_user_org_role(auth.uid(), organization_id) returns 'owner' or 'admin'.

Sources: CLAUDE.md:278-296, src/integrations/supabase/types.ts:685-693

To avoid recursive evaluation and performance bottlenecks, the system uses security definer functions instead of inline subqueries within RLS policies.

• get_user_org_role(_org_id, _user_id): Returns the specific role of a user.
• is_organization_member(_org_id, _user_id): Boolean check for membership.

Sources: CLAUDE.md:301-310, src/integrations/supabase/types.ts:685-693

When a new organization is created, the system automatically establishes the initial access control boundary by assigning the creator the 'owner' role.

sequenceDiagram
    participant User
    participant Page as CreateOrganization Page
    participant DB as Supabase Database
    
    User->>Page: Submit Name & Slug
    Page->>DB: INSERT INTO organizations
    DB-->>Page: Success (Organization ID)
    Page->>DB: INSERT INTO organization_members (owner role)
    Note over DB: Sets user_id as OWNER for org_id
    DB-->>Page: Success
    Page->>User: Redirect to Setup/Dashboard

Sources: src/pages/CreateOrganization.tsx:88-115

Access control extends beyond simple membership to managing high-risk resources like GitHub integrations and automated workflows.

• Integration Management: Only Owners and Admins can view or modify sensitive configuration data in organization_integrations.
• Workflow Authorization: The organization_workflows table tracks created_by (uuid) to ensure auditability and restricts modification to administrative roles.

Sources: src/pages/OrganizationDashboard.tsx:288-294, src/integrations/supabase/types.ts:537-573

Organization Access Control in Colabs provides a robust framework for multi-tenant collaboration. By combining frontend feature gating with deep database-level RLS policies and a clear role hierarchy (Owner, Admin, Member), the system ensures that organizational data and external integrations remain secure while enabling seamless team management.

Contributor Profiles & Analytics serve as the core reputation and visualization engine of the Colabs platform. This system unifies real-world GitHub activity—including commits, pull requests, and coding streaks—into a comprehensive developer profile. By transforming raw contribution data into actionable insights, the platform enables developers to build a verifiable track record and allows project owners to assess contributor expertise through data-driven metrics.

The analytics suite provides multi-layered visualizations, ranging from high-level contribution heatmaps to granular tech-stack proficiency breakdowns. These features are designed to gamify open-source participation while providing professional-grade reporting for both individual contributors and organizations.

Sources: README.md:52-53, README.md:104-106, src/components/AnalyticsSection.tsx:13-19

The user profile is the central hub for showcasing a developer's identity and their impact within the ecosystem. It integrates personal metadata with live contribution statistics synchronized from external version control providers.

A contributor profile aggregates several data points to establish professional identity:

• Identity Details: Full name, email-based initials, and GitHub username.
• Social & External Links: Direct links to GitHub profiles and personal portfolios.
• Tenure Tracking: "Joined" dates to show platform longevity.
• Gamification Badges: Visual indicators for achievements such as "Top 10% Contributor" and contribution streaks.

Sources: src/pages/Profile.tsx:126-160, src/pages/Profile.tsx:162-175

The profile page utilizes a mix of authenticated user data from Supabase and mock data (in current implementation) to populate various visualization components.

flowchart TD
    Auth[useAuth Hook] --> UserData[User Metadata]
    UserData --> Header[Profile Header]
    
    subgraph Analytics_Engine[Analytics Components]
        Heatmap[Contribution Heatmap]
        Stack[Tech Stack Progress]
        Activity[Recent Activity Timeline]
    end
    
    UserData -.->|User ID| Analytics_Engine
    MockData[(Mock Stats)] --> Analytics_Engine

The diagram above illustrates how the profile page orchestrates user information and analytics components to render the full contributor view. Sources: src/pages/Profile.tsx:112-124, src/components/dashboard/AnalyticsTab.tsx:49-65

The analytics system is composed of several specialized components that translate git activity into visual charts.

The platform tracks four primary key performance indicators (KPIs) for contributors:

Proficiency is calculated based on project usage and language frequency. It is visualized using progress bars and radar charts to show a developer's expertise across different technologies.

graph TD
    A[Project Activity] --> B{Language Detection}
    B -->|Frequency| C[Proficiency Score]
    B -->|Usage| D[Project Count]
    C --> E[Progress Bar Visualization]
    D --> E

This logic enables the "Tech Proficiency" radar chart and "Tech Stack" list seen in the dashboard and profile sections. Sources: src/components/InteractiveDemoSection.tsx:142-162, src/pages/Profile.tsx:210-224

The heatmap provides a GitHub-style 12-month (or 140-day in specific views) grid representing daily activity intensity.

• Data Structure: An array of objects containing date and count.
• Visual Logic: Color intensity shifts from bg-muted/30 (no activity) to bg-primary (high activity).

Sources: src/components/dashboard/AnalyticsTab.tsx:39-48, src/components/InteractiveDemoSection.tsx:181-218

Analytics are also aggregated at the project level, allowing maintainers to see the health and activity of their repositories.

When a GitHub URL is linked to a project, the system fetches live data including:

• Star/Fork Counts: Overall project popularity.
• Open Issues: Active tasks available for contributors.
• Contributor List: A visual gallery of users who have contributed to the specific repository, including their individual contribution counts.

Sources: src/pages/Project.tsx:43-62, src/pages/Project.tsx:327-353

sequenceDiagram
    participant P as Project Page
    participant S as Supabase Edge Function
    participant G as GitHub API
    
    P->>S: invoke('github-project-data', {repoUrl})
    S->>G: GET /repos/{owner}/{repo}
    G-->>S: Repo Metadata, Stars, Forks
    S->>G: GET /repos/{owner}/{repo}/contributors
    G-->>S: Contributor List & Counts
    S-->>P: Return Unified GitHubData Object
    P->>P: Render Contributor Avatars & Stats

This sequence details how project-specific contributor analytics are retrieved and displayed. Sources: src/pages/Project.tsx:135-152, supabase/functions/github-issues/index.ts:1-20

For teams and organizations, the platform provides advanced metrics to track collective velocity and individual performance within a workspace.

Organizations can access insights designed for Technical Team Leads and Product Managers:

• Commit Frequency: Tracking how often code is pushed to organization repos.
• Developer Skill Assessment: Tracking skill development across different technologies within the team.
• Workflow Velocity: Monitoring the transition of tasks from todo to done.
• Time Allocation: Understanding how developer time is distributed across various projects.

Sources: src/components/OrganizationsSection.tsx:50-85, src/components/dashboard/TeamWorkspace.tsx:442-466

Contributor Profiles & Analytics in Colabs provide a robust framework for quantifying and displaying developer impact. By integrating directly with GitHub and using specialized visualization components like heatmaps, radar charts, and proficiency bars, the platform creates a data-rich environment for developers to prove their skills and for organizations to optimize their team's performance. This system is critical for the platform's goal of connecting verified talent with open-source and freelance opportunities.

Sources: README.md:27-32, src/components/AnalyticsSection.tsx:64-75

Global Search & Navigation in the Colabs platform facilitates efficient discovery of open-source projects, freelance gigs, and collaborative teams. The system is designed to provide seamless transitions between the main dashboard, project explorers, and organization-specific workspaces. It integrates metadata-driven SEO and structured data to ensure that the platform's content is discoverable both internally via search interfaces and externally through search engines.

The navigation architecture utilizes a single-page application (SPA) approach powered by React Router DOM, with dedicated layouts like AppLayout and TopNavLayout to maintain UI consistency across different functional modules. Internal search functionality is implemented through filtering systems that allow users to query by title, ID, labels, and metadata across various entities such as issues and projects.

Sources: CLAUDE.md:14-38, index.html:10-90, src/pages/Project.tsx:98-105

The project employs a structured routing system where pages are organized as route-level components within src/pages/. Navigation is handled through several specialized layouts and UI components that facilitate movement between feature-specific areas.

Navigation is categorized into primary site-wide links and contextual sub-navigation:

• Top-Level Routes: Defined in App.tsx, directing users to the Dashboard, Projects, Organizations, and Gigs.
• Contextual Nav: Components like ArrowLeft are used in detailed views (e.g., Project page or Submit Proposal) to provide a "Back" navigation path to previous lists.
• Role-Based Access: Navigation elements change based on user session and organization role (Owner, Admin, Member).

Sources: CLAUDE.md:145-155, src/pages/Project.tsx:160-165, src/pages/OrganizationDashboard.tsx:158-164

The following diagram illustrates the flow from a user interaction to a route change and subsequent data fetching for the target page.

flowchart TD
    User([User Interaction]) --> Click[Click NavLink/Button]
    Click --> Router[React Router DOM]
    Router --> Page[Load Route Component]
    Page --> Layout[Apply AppLayout/TopNavLayout]
    Layout --> DataFetch[Fetch Page Metadata/Data]
    DataFetch --> Supabase[(Supabase DB)]
    Supabase -- Result --> PageRender[Render Component with Data]

The navigation flow ensures that as a user moves between modules (e.g., from Organizations to a specific Organization Dashboard), the system fetches the necessary permissions and data associated with that specific slug or ID.

Sources: src/pages/OrganizationDashboard.tsx:75-120, CLAUDE.md:200-210

The search capability in Colabs is primarily decentralized into specialized filter bars and search inputs within specific modules like the Issues Tab and Project Explorer.

Sources: src/components/dashboard/IssuesTab.tsx:365-375, index.html:98-110

The IssuesTab component implements a robust filtering and sorting engine. Users can refine their view based on several parameters which are processed reactively.

flowchart TD
    Input[Search Query / Filter Selection] --> Logic{Filter Logic}
    Logic -->|Text Match| Text[Title/ID Match]
    Logic -->|Status| StatusSet[filterStatuses Set]
    Logic -->|Priority| PrioritySet[filterPriorities Set]
    Logic -->|Labels| LabelSet[filterLabels Set]
    Text & StatusSet & PrioritySet & LabelSet --> Sort[Sorting Engine]
    Sort --> Result[Filtered & Sorted Array]
    Result --> Render[Render List/Kanban]

Sources: src/components/dashboard/IssuesTab.tsx:363-390

To enhance global discoverability outside the application, the system uses index.html to define primary metadata and JSON-LD structured data.

• Primary Meta: Defines the "Colabs" identity, description, and canonical URL.
• JSON-LD: Provides search engines with a WebSite graph including a potentialAction for SearchAction. This enables search engines to recognize the /projects?q={search_term_string} pattern as an internal search entry point.
• Open Graph: Ensures rich link previews when pages are shared on social platforms.

Sources: index.html:9-55, index.html:95-112

Within organizations, navigation is divided into tabs that allow users to toggle between "Overview", "Integrations", "Workflows", and "Members". This keeps navigation scoped to the specific organization context.

sequenceDiagram
    participant User
    participant OrgDash as Organization Dashboard
    participant DB as Supabase
    User->>OrgDash: Enter /org/:slug
    OrgDash->>DB: Fetch Org details by Slug
    DB-->>OrgDash: Return Org & Member Role
    OrgDash->>OrgDash: Set Active Tab (Overview)
    User->>OrgDash: Click "Integrations" Tab
    OrgDash->>OrgDash: Update Local State/Route
    OrgDash->>User: Display Integration Cards

Sources: src/pages/OrganizationDashboard.tsx:143-220

Project pages use a back-navigation pattern (navigate(-1)) and include breadcrumbs or back-buttons to return to the project explorer. They also link out to external tools like GitHub, Figma, and Slack, which are stored in the external_links JSONB field in the database.

Sources: src/pages/Project.tsx:132-135, src/pages/Project.tsx:243-268

The Global Search & Navigation system in Colabs combines internal React-based routing and client-side filtering with external SEO strategies. By using standardized layouts and contextual back-navigation, it ensures a consistent user experience while browsing various open-source and freelance opportunities. Discovery is further supported by metadata-rich project and organization dashboards that integrate live data from the Supabase backend and external GitHub APIs.

Sources: CLAUDE.md:14-25, index.html:105-110, src/pages/Project.tsx:405-415