PLAN.md
4,823 bytes
| 1 | # PLAN.md — profileShare |
|---|---|
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | 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] |
| 6 | |
| 7 | ## Core Concept |
| 8 | |
| 9 | - A GitHub-like read-only view, shareable by URL. [S1][S11] |
| 10 | - Lets the owner share **selected** repositories plus profile and activity, not everything. [S3][S9][S13] |
| 11 | - Viewers do **not** need a GitHub account of their own. [S5] |
| 12 | - Each link is a **snapshot** taken at creation time, not a live view that updates. [S14][S15] |
| 13 | - Links expire after a customizable time period (e.g. 7 days). [S9][S20] |
| 14 | |
| 15 | ## Users |
| 16 | |
| 17 | - **Owner / creator:** initially the developer themselves; possibly opened up to other sign-ups later (undecided). [S6][S7] |
| 18 | - **Viewers:** mainly people who might hire the owner; they only view, they do not sign in. [S5] |
| 19 | |
| 20 | ## Data Source & Permissions |
| 21 | |
| 22 | - Content is pulled from the owner's **GitHub** account. [S16][S17] |
| 23 | - Owner authorizes access via GitHub login/approval. [S18] |
| 24 | - Access should be limited to **only the repositories the owner chooses to share**, not all repositories. [S19] |
| 25 | |
| 26 | ## Owner Flow |
| 27 | |
| 28 | 1. Owner logs in and connects GitHub. [S17][S18] |
| 29 | 2. Owner sees their repos and clicks to select which ones to share. [S9][S37] |
| 30 | 3. Owner sets an expiration period (customizable, e.g. 7 days). [S9] |
| 31 | 4. The tool generates a profile page and a simple shareable URL. [S9] |
| 32 | 5. Owner sends the link to whomever they choose. [S9] |
| 33 | |
| 34 | ## Viewer Flow |
| 35 | |
| 36 | 1. Viewer opens the link and lands on the **main profile page**. [S39] |
| 37 | 2. From the profile, they click into a shared **repository**. [S38][S39] |
| 38 | 3. Inside a repository they can browse **files** and view **commit history**. [S11][S40] |
| 39 | 4. Files open on screen to read the code; nested folders can be opened. [S44][S45] |
| 40 | 5. A **button at the top** returns them to the profile page. [S47] |
| 41 | |
| 42 | ## Page Content |
| 43 | |
| 44 | 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] |
| 45 | |
| 46 | Per-repository view should include: |
| 47 | - List of files (browsable, including nested folders). [S44][S45] |
| 48 | - Code viewable on screen. [S44] |
| 49 | - Commit history — a list of what changed and when. [S11][S42] |
| 50 | - Commits should be clickable to see the changed lines **if feasible**. [S43] |
| 51 | |
| 52 | ## Expiration Behavior |
| 53 | |
| 54 | - When a link is opened after it has expired, show a simple message: **"the URL you have opened is expired."** [S20][S21] |
| 55 | |
| 56 | ## Access / Security Model |
| 57 | |
| 58 | - Link-based access only; no per-viewer identity checks. [S22][S23] |
| 59 | - 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] |
| 60 | |
| 61 | ## Explicitly Out of Scope |
| 62 | |
| 63 | - No comments. [S30][S31] |
| 64 | - No downloading of code. [S30][S31] |
| 65 | - No editing by viewers. [S32][S33] |
| 66 | - Not a full clone of everything GitHub does. [S32][S33] |
| 67 | - Not team-oriented — a single-person overview of code. [S32][S33] |
| 68 | |
| 69 | ## Platform |
| 70 | |
| 71 | - Primarily intended to be viewed on a **computer/desktop**. [S28][S29] |
| 72 | |
| 73 | ## Verification (Owner's Acceptance Check) |
| 74 | |
| 75 | - Owner opens the generated link themselves to review it. [S34][S35] |
| 76 | - It is "right" if it shows **all the projects the owner selected** and **all the commits**. [S36][S37] |
| 77 | |
| 78 | ## Open / Undecided Questions |
| 79 | |
| 80 | - Whether to support other users signing up to share their own profiles. [S7] |
| 81 | - Whether to delete the stored snapshot immediately on expiration or retain it afterward — owner deferred to "best solution." [S26][S27] |
| 82 | - Size/quantity/performance limits — none specified; should "just work normally." [S24][S25] |
| 83 | - 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] |
| 84 | |
| 85 | ## Decisions Already Made |
| 86 | |
| 87 | | Decision | Choice | Source | |
| 88 | |---|---|---| |
| 89 | | Sharing mechanism | Simple shareable URL | [S9] | |
| 90 | | Content freshness | Snapshot at creation, not live | [S14][S15] | |
| 91 | | Link lifetime | Time-limited, customizable (e.g. 7 days) | [S9] | |
| 92 | | Expired link | Show "expired" message | [S20][S21] | |
| 93 | | Source of data | GitHub | [S16][S17] | |
| 94 | | Repo access scope | Only selected repos | [S19] | |
| 95 | | Viewer accounts | Not required | [S5] | |
| 96 | | Access control | Link-based only, forwarding tolerated | [S22][S23] | |
| 97 | | Viewer capabilities | Read-only overview; no comments/download/edit | [S30][S31][S32][S33] | |
| 98 | | Target platform | Desktop/computer | [S28][S29] | |
| 99 | | Navigation | Profile → repo → files/commits; top button back to profile | [S38][S39][S47] | |
| 100 | | Commit detail | Clickable diffs if feasible | [S43] | |