Deep links and URL state
What goes in the address so a view can be shared and reloaded.
The address says which tab of a page you're on, so a link opens exactly that view and reloading keeps it. Nothing else lives in the address yet.
The problem
Other Bridge apps, emails and people send links into Bridge OS: "look at the intros with Quillbase", "connect your AI app in Settings". If the address doesn't say which tab is open, every link lands on the default view, a reload loses your place, and copying the address shares the wrong thing.
What to do
- The address names the tab. A page with tabs puts the selected one in the address as
?tab=<key>. The default tab has no parameter, so the plain address is the normal view. - A bad link still opens the page. A missing, unknown or unavailable tab opens the default tab. A link never lands on an error because of its
?tab=. - Switching tabs keeps the address true, without filling Back. Each switch replaces the address rather than adding to history, so the current address can always be copied, and Back leaves the page instead of stepping through tabs.
Which one do I use?
| Situation | Do this | Bridge example |
|---|---|---|
| A page with tabs (an organization, Settings) | ?tab=<key>, lowercase, hyphenated; nothing for the default tab | /network/quillbase.example?tab=intros, /settings?tab=mcp |
| A tab that only exists with data (Investors, Portfolio, Guests) | Keep the asked-for tab while the counts load; if the data isn't there, open the default tab | ?tab=investors on a company with no investors opens People |
| A sub-page whose back link depends on where you came from | Say it in the address with ?from= | /profile/intros?from=outcomes shows "Back to Outcomes" |
| A person or organization | Its own page, so the path itself is the link | /network/{domain}, /to/{username} |
| An app's details, opened from the apps page | The same address opens as an overlay when clicked, and as a full page when visited directly | /app/{id} |
| A drawer, a menu, a half-typed search | Nothing in the address today | Opening an intro's drawer leaves the address as it was |
See it work
Live examples built from the package on the sample network. Click through them.
Switching tabs updates the address
Click through the tabs. The address follows, and People, the default, drops the parameter.
Quillbase
Priya Natarajan
Co-founder & CEO
Daniel Osei
Co-founder & CTO
os.brdg.app/network/quillbase.example
Opening a link, good or bad
Open each link. A known tab opens on that tab; one the organization doesn't have, or a mistyped one, opens People.
/network/quillbase.example?tab=intros/network/quillbase.example?tab=investors/network/quillbase.example?tab=Intro/network/quillbase.example
The address says where you came from
`?from=outcomes` makes Your intros point back to Outcomes; without it, back to your profile.
Your intros
os.brdg.app/profile/intros?from=outcomes
What to write
| Part | Rule | Example |
|---|---|---|
| Tab key | The tab's name, lowercase, words joined by a hyphen. Never a number or an internal code. | connectors, co-investors |
| Default tab | No parameter at all. Don't write the default into links. | /network/quillbase.example, not ?tab=people |
| Organization path | The bare domain, no www. and no https://. | /network/quillbase.example |
| Links from other apps | Relative to the Bridge OS address, using the exact keys on this page. | /network/invites?tab=sent |
Approved, not built yet
- Search text, filters and page number also go in the address (
?q=,?degree=,?page=), so a filtered list can be shared and survives a reload. - Signing in returns people to the page they were trying to open.
Accessibility
- Changing the tab doesn't move focus or reload the page: focus stays on the tab you chose.
- Because tabs replace the address instead of adding history, Back does what people expect: it leaves the page.
- A link that falls back to the default tab still opens a working page with the right tab marked as selected.
| Keys | What happens |
|---|---|
| ← / → | Moves between tabs. The address changes when a tab is opened, not while focus moves. |
| Enter / Space | Opens the focused tab and updates the address. |
Components this uses
Not decided yet
Proposals for Aman to approve, change or reject. Not rules.
- Whether an open drawer (an intro, a relationship) should get its own address, so it can be shared and reopened.
- Whether a fallback should also clean the address: today
?tab=investorsstays in the address while People shows.
Where Bridge OS differs today
Follow this page, not the gap.
- Activity rail tabs, feed filters and intro status tabs aren't in the address.
- Signed out on a *.brdg.app page, sign-in loses where the person was going.
- When a link asks for a tab the organization doesn't have, the page shows People but the address keeps the old
?tab=until you switch tabs.
Sources
- Bridge OS
docs/DEEP-LINKS.md - Bridge OS
org-network-content.tsx,settings-content.tsx - Bridge OS
docs/DEEP-LINKS.md;org-network-content.tsx - Bridge OS
src/lib/settings/settings-tab.ts - Bridge OS
app/(shell)/profile/intros/page.tsx - Bridge OS
CLAUDE.md→ parallel route interception (@modal/(...)app/[id]) - Bridge OS intro-detail-drawer, relationship-detail-drawer, week-contacts-drawer
- Bridge OS
docs/DEEP-LINKS.md→ Notes for link authors - Proposals approved by Aman 2026-11-02.