Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
| 1 | # Toolkits Page - Implementation Plan |
| 2 | |
| 3 | ## Decisions Made |
| 4 | |
| 5 | ### No Sidebar |
| 6 | - Toolkits section has no sidebar navigation |
| 7 | - Only breadcrumb navigation (`← Back to Toolkits`) |
| 8 | - Keeps UI clean, avoids 855 items in sidebar |
| 9 | |
| 10 | ### No Input Parameters on Toolkit Pages |
| 11 | - Users don't need param schemas in docs |
| 12 | - LLMs read schemas automatically |
| 13 | - Platform playground is better for exploring params |
| 14 | |
| 15 | ### No Scopes Display |
| 16 | - We only have scope names, not descriptions |
| 17 | - Raw scope strings aren't useful to users |
| 18 | - Just show auth method badge (OAuth2, API_KEY, etc.) |
| 19 | |
| 20 | ### Search-First Experience |
| 21 | - Landing page shows search + category filter + cards |
| 22 | - Don't render all 855 cards upfront |
| 23 | - Filter client-side from pre-generated JSON |
| 24 | - The Instant Tools card toggles an eligibility filter and intersects with search. |
| 25 | The guide remains a separate link. Instant eligibility is refreshed through the |
| 26 | server-only `/api/toolkits/instant` route from the paginated production catalog, |
| 27 | cached for five minutes and merged only into existing snapshot rows. Missing |
| 28 | eligibility or failed requests show a retry state, not a false empty catalog. |
| 29 | The API key stays on the server. Neutral Nucleo outline bolts match the |
| 30 | dashboard; a filled bolt denotes the selected filter, not project access. |
| 31 | |
| 32 | ### Build-Time Generation |
| 33 | - `bun run generate:toolkits` - separate command |
| 34 | - Not run on `bun run dev` (too slow) |
| 35 | - Run on CI push |
| 36 | - JSON files committed to git (works offline) |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## URL Structure |
| 41 | |
| 42 | ``` |
| 43 | /toolkits → Landing page (search + filter + cards) |
| 44 | /toolkits/pro-tools → Pro tools pricing/limits info |
| 45 | /toolkits/{slug} → Individual toolkit page |
| 46 | ``` |
| 47 | |
| 48 | --- |
| 49 | |
| 50 | ## Landing Page (`/toolkits`) |
| 51 | |
| 52 | ``` |
| 53 | ┌─────────────────────────────────────────────────────────────┐ |
| 54 | │ Toolkits [Request Tools →] │ |
| 55 | │ All the toolkits that we support. │ |
| 56 | │ │ |
| 57 | │ 🔍 Search toolkits... │ |
| 58 | │ │ |
| 59 | │ [All] [Communication] [Developer Tools] [CRM] [Storage]... │ |
| 60 | │ │ |
| 61 | │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ |
| 62 | │ │ Gmail │ │ Slack │ │ GitHub │ │ |
| 63 | │ │ GMAIL │ │ SLACK │ │ GITHUB │ │ |
| 64 | │ │ desc... │ │ desc... │ │ desc... │ │ |
| 65 | │ │[OAUTH2] │ │[OAUTH2] │ │[OAUTH2] │ │ |
| 66 | │ │ 🔧37 ⚡2 │ │ 🔧130 ⚡9│ │ 🔧829 ⚡6│ │ |
| 67 | │ └─────────┘ └─────────┘ └─────────┘ │ |
| 68 | │ │ |
| 69 | │ ⭐ Some tools are pro tools. [Learn about pricing →] │ |
| 70 | └─────────────────────────────────────────────────────────────┘ |
| 71 | ``` |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | ## Individual Toolkit Page (`/toolkits/{slug}`) |
| 76 | |
| 77 | ``` |
| 78 | ┌─────────────────────────────────────────────────────────────┐ |
| 79 | │ ← Back to Toolkits │ |
| 80 | │ │ |
| 81 | │ [Logo] Gmail [Open in Platform →] │ |
| 82 | │ GMAIL (copy) │ |
| 83 | │ Gmail is Google's email service... │ |
| 84 | │ │ |
| 85 | │ [OAuth2] 37 Tools 2 Triggers Communication │ |
| 86 | ├─────────────────────────────────────────────────────────────┤ |
| 87 | │ ## Authentication │ |
| 88 | │ This toolkit uses OAuth2. │ |
| 89 | │ [Create Auth Config →] [How authentication works →] │ |
| 90 | ├─────────────────────────────────────────────────────────────┤ |
| 91 | │ ## Tools │ |
| 92 | │ 🔍 Search tools... │ |
| 93 | │ │ |
| 94 | │ | Name | Description │ |
| 95 | │ |-------------------|---------------------------------------| |
| 96 | │ | Send email | Sends an email message to... │ |
| 97 | │ | Create draft | Creates a draft email... │ |
| 98 | ├─────────────────────────────────────────────────────────────┤ |
| 99 | │ ## Triggers (only if count > 0) │ |
| 100 | │ | Name | Description │ |
| 101 | │ |-------------------|---------------------------------------| |
| 102 | │ | New email | Fires when a new email arrives... │ |
| 103 | └─────────────────────────────────────────────────────────────┘ |
| 104 | ``` |
| 105 | |
| 106 | --- |
| 107 | |
| 108 | ## Data & Generation |
| 109 | |
| 110 | ### Single File Architecture |
| 111 | |
| 112 | All toolkit data (including tools and triggers) is stored in a **single JSON file**: |
| 113 | |
| 114 | ``` |
| 115 | /public/data/toolkits.json → All toolkits with tools & triggers (~5-10MB) |
| 116 | ``` |
| 117 | |
| 118 | ### Why Single File? |
| 119 | |
| 120 | - **Fully static** - No API calls at runtime, fast and reliable |
| 121 | - **No repo bloat** - One file instead of 800+ individual files |
| 122 | - **Git-friendly** - Git compresses JSON well |
| 123 | - **Simple** - Easy to understand and maintain |
| 124 | - **Open source friendly** - Public data, no secrets |
| 125 | |
| 126 | ### Generator Script |
| 127 | `scripts/generate-toolkits.ts` |
| 128 | |
| 129 | Run: `bun run generate:toolkits` |
| 130 | |
| 131 | ### JSON Structure |
| 132 | |
| 133 | ```json |
| 134 | // toolkits.json |
| 135 | [ |
| 136 | { |
| 137 | "slug": "gmail", |
| 138 | "name": "Gmail", |
| 139 | "logo": "https://...", |
| 140 | "description": "Gmail is Google's...", |
| 141 | "category": "Communication", |
| 142 | "authSchemes": ["OAUTH2"], |
| 143 | "toolCount": 37, |
| 144 | "triggerCount": 2, |
| 145 | "version": "20260102_00", |
| 146 | "tools": [ |
| 147 | { "slug": "GMAIL_SEND_EMAIL", "name": "Send email", "description": "..." } |
| 148 | ], |
| 149 | "triggers": [ |
| 150 | { "slug": "GMAIL_NEW_EMAIL", "name": "New email", "description": "..." } |
| 151 | ] |
| 152 | } |
| 153 | ] |
| 154 | ``` |
| 155 | |
| 156 | --- |
| 157 | |
| 158 | ## Scripts |
| 159 | |
| 160 | ```json |
| 161 | { |
| 162 | "scripts": { |
| 163 | "dev": "next dev", |
| 164 | "build": "next build", |
| 165 | "generate:toolkits": "bun scripts/generate-toolkits.ts" |
| 166 | } |
| 167 | } |
| 168 | ``` |
| 169 | |
| 170 | | Command | Regenerates? | Use case | |
| 171 | |---------|--------------|----------| |
| 172 | | `bun run dev` | ❌ | Local dev | |
| 173 | | `bun run build` | ❌ | Fast build | |
| 174 | | `bun run generate:toolkits` | ✅ | Manual | |
| 175 | | CI push | ✅ | Auto regenerate | |
| 176 | |
| 177 | --- |
| 178 | |
| 179 | ## Components to Build |
| 180 | |
| 181 | 1. `ToolkitSearch` - Search input |
| 182 | 2. `CategoryFilter` - Filter chips |
| 183 | 3. `ToolkitCard` - Individual card |
| 184 | 4. `ToolkitGrid` - Cards container |
| 185 | 5. `ToolsTable` - Searchable tools table |
| 186 | 6. `Breadcrumb` - Navigation |
| 187 | |
| 188 | --- |
| 189 | |
| 190 | ## Implementation Order |
| 191 | |
| 192 | 1. [x] Generator script (`scripts/generate-toolkits.ts`) |
| 193 | 2. [x] Landing page + components (category grouping, alphabet sections) |
| 194 | 3. [x] Individual toolkit page (version display, auth badges, tool/trigger list with copy) |
| 195 | 4. [x] Pro tools page (`/toolkits/pro-tools`) |
| 196 | 5. [x] Hybrid architecture (static index + server-side API fetch) |
| 197 | 6. [ ] Polish/styling |
| 198 | 7. [ ] CI hooks for auto-regeneration |
| 199 | |
| 200 | --- |
| 201 | |
| 202 | ## FAQ Section |
| 203 | |
| 204 | ### How It Works |
| 205 | - Per-toolkit FAQ sourced from plain markdown files in `content/toolkits/faq/{toolkit-slug}.md` |
| 206 | - `##` headings are questions, body text is the answer |
| 207 | - Markdown is converted to HTML at build time using `remark-parse` + `remark-rehype` + `hast-util-to-html` (all transitive deps from Fumadocs, no new packages) |
| 208 | - Rendered as Fumadocs `Accordion` components between the Header and Auth Details sections |
| 209 | - Only shown if a `.md` file exists for that toolkit and has valid Q&A content |
| 210 | |
| 211 | ### Copy Page / LLM Markdown |
| 212 | - FAQ content is also included in the `/toolkits/{slug}.md` LLM route output |
| 213 | - Heading levels are bumped (`##` → `###`) so questions are children of the `## Frequently Asked Questions` section |
| 214 | |
| 215 | ### No Sitemap Impact |
| 216 | - FAQ is embedded within existing toolkit pages — no new URLs are created |
| 217 | - No changes to sitemap or routing |
| 218 | |
| 219 | ### Adding FAQ Content |
| 220 | - Create/edit `content/toolkits/faq/{toolkit-slug}.md` — no code changes needed |
| 221 | - Empty files or files with no valid `##` headings are safely ignored |
| 222 | |
| 223 | --- |
| 224 | |
| 225 | ## Future: CI Hooks |
| 226 | |
| 227 | - Trigger docs regeneration from toolkit repo changes |
| 228 | - Trigger docs regeneration from API repo changes |