PLAN.md — profileShare

Overview

profileShare is a tool for sharing a read-only overview of your GitHub work — your profile and selected repositories — through a simple, time-limited link. The goal is to let people (mainly potential employers) view chosen private repos and profile information without making those repos fully public and without adding viewers as collaborators. [S1][S5][S13]

Core Concept

• A GitHub-like read-only view, shareable by URL. [S1][S11]
• Lets the owner share selected repositories plus profile and activity, not everything. [S3][S9][S13]
• Viewers do not need a GitHub account of their own. [S5]
• Each link is a snapshot taken at creation time, not a live view that updates. [S14][S15]
• Links expire after a customizable time period (e.g. 7 days). [S9][S20]

Users

• Owner / creator: initially the developer themselves; possibly opened up to other sign-ups later (undecided). [S6][S7]
• Viewers: mainly people who might hire the owner; they only view, they do not sign in. [S5]

Data Source & Permissions

• Content is pulled from the owner's GitHub account. [S16][S17]
• Owner authorizes access via GitHub login/approval. [S18]
• Access should be limited to only the repositories the owner chooses to share, not all repositories. [S19]

Owner Flow

1. Owner logs in and connects GitHub. [S17][S18]
2. Owner sees their repos and clicks to select which ones to share. [S9][S37]
3. Owner sets an expiration period (customizable, e.g. 7 days). [S9]
4. The tool generates a profile page and a simple shareable URL. [S9]
5. Owner sends the link to whomever they choose. [S9]

Viewer Flow

1. Viewer opens the link and lands on the main profile page. [S39]
2. From the profile, they click into a shared repository. [S38][S39]
3. Inside a repository they can browse files and view commit history. [S11][S40]
4. Files open on screen to read the code; nested folders can be opened. [S44][S45]
5. A button at the top returns them to the profile page. [S47]

Page Content

Main profile page should include standard GitHub/GitLab-style profile information (e.g. name, photo, bio) and the list of selected projects, plus profile activity. [S3][S12][S13]

Per-repository view should include:

• List of files (browsable, including nested folders). [S44][S45]
• Code viewable on screen. [S44]
• Commit history — a list of what changed and when. [S11][S42]
• Commits should be clickable to see the changed lines if feasible. [S43]

Expiration Behavior

• When a link is opened after it has expired, show a simple message: "the URL you have opened is expired." [S20][S21]

Access / Security Model

• Link-based access only; no per-viewer identity checks. [S22][S23]
• If a link is forwarded, that is acceptable — the point is only to avoid making repos public to the whole world, not to lock down to specific individuals. [S23]

Explicitly Out of Scope

• No comments. [S30][S31]
• No downloading of code. [S30][S31]
• No editing by viewers. [S32][S33]
• Not a full clone of everything GitHub does. [S32][S33]
• Not team-oriented — a single-person overview of code. [S32][S33]

Platform

• Primarily intended to be viewed on a computer/desktop. [S28][S29]

Verification (Owner's Acceptance Check)

• Owner opens the generated link themselves to review it. [S34][S35]
• It is "right" if it shows all the projects the owner selected and all the commits. [S36][S37]

Open / Undecided Questions

• Whether to support other users signing up to share their own profiles. [S7]
• Whether to delete the stored snapshot immediately on expiration or retain it afterward — owner deferred to "best solution." [S26][S27]
• Size/quantity/performance limits — none specified; should "just work normally." [S24][S25]
• Detailed in-project navigation (back-out of files, stepping up through nested folders, jump to project root) left to the implementer. [S40][S41][S48][S49]

Decisions Already Made