Update documentation with overview and architecture
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
@startuml
|
||||
!define RECTANGLE class
|
||||
|
||||
skinparam componentStyle rectangle
|
||||
skinparam backgroundColor #FEFEFE
|
||||
|
||||
package "Landing Page Architecture" {
|
||||
|
||||
component "Hero Section" as hero {
|
||||
[Value Proposition]
|
||||
[Install Command]
|
||||
[Primary CTAs]
|
||||
}
|
||||
|
||||
component "Quick Start" as quickstart {
|
||||
[3-Step Visual Guide]
|
||||
}
|
||||
|
||||
component "Popular Tools" as popular {
|
||||
[6 Tool Cards]
|
||||
[API: GET /tools?sort=downloads&limit=6]
|
||||
}
|
||||
|
||||
component "Why SmartTools" as why {
|
||||
[3 Pillars]
|
||||
[Easy | Powerful | Community]
|
||||
}
|
||||
|
||||
component "Latest Tutorials" as tutorials {
|
||||
[3 Tutorial Cards]
|
||||
[API: GET /content/tutorials?limit=3]
|
||||
}
|
||||
|
||||
component "Contributor Spotlight" as spotlight {
|
||||
[Monthly Featured Contributor]
|
||||
}
|
||||
|
||||
component "Footer" as footer {
|
||||
[Navigation Links]
|
||||
[Donate CTA]
|
||||
[Social | Legal]
|
||||
}
|
||||
|
||||
component "Ad Slots" as ads {
|
||||
[Sidebar (desktop only)]
|
||||
[Optional Footer Banner]
|
||||
}
|
||||
|
||||
database "Registry API" as api
|
||||
cloud "AdSense" as adsense
|
||||
|
||||
hero -down-> quickstart
|
||||
quickstart -down-> popular
|
||||
popular -down-> why
|
||||
why -down-> tutorials
|
||||
tutorials -down-> spotlight
|
||||
spotlight -down-> footer
|
||||
|
||||
popular ..> api : lazy load
|
||||
tutorials ..> api : lazy load
|
||||
ads ..> adsense : async
|
||||
|
||||
note right of hero
|
||||
Critical path:
|
||||
- FCP < 1.5s
|
||||
- TTI < 3s
|
||||
- No layout shift
|
||||
end note
|
||||
|
||||
note right of popular
|
||||
API response cached:
|
||||
- 5 min server-side
|
||||
- ETag/Last-Modified
|
||||
end note
|
||||
|
||||
note right of ads
|
||||
Load strategy:
|
||||
- Async after content
|
||||
- Reserved height
|
||||
- Fallback if blocked
|
||||
end note
|
||||
}
|
||||
|
||||
package "Responsive Breakpoints" {
|
||||
[Mobile <640px] --> [Single column, ads hidden]
|
||||
[Tablet 640-1024px] --> [2-col optional, footer ads]
|
||||
[Desktop >1024px] --> [Full layout, sidebar ads]
|
||||
}
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,90 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
skinparam backgroundColor #FEFEFE
|
||||
skinparam shadowing false
|
||||
|
||||
title SmartTools Landing Page Architecture
|
||||
|
||||
package "Client Browser" {
|
||||
[User] as User
|
||||
[HTML/CSS/JS] as Frontend
|
||||
[Service Worker\n(future)] as SW
|
||||
}
|
||||
|
||||
package "Web Server (Flask)" {
|
||||
[Landing Page\nController] as LandingCtrl
|
||||
[Template Engine\n(Jinja)] as Jinja
|
||||
[Static Assets\nHandler] as StaticAssets
|
||||
}
|
||||
|
||||
package "Registry API" {
|
||||
[GET /api/v1/stats/summary] as StatsAPI
|
||||
[GET /api/v1/tools?sort=downloads&limit=6] as ToolsAPI
|
||||
[GET /api/v1/content/announcements] as AnnouncementsAPI
|
||||
}
|
||||
|
||||
package "Data Layer" {
|
||||
database "SQLite/PostgreSQL" as DB
|
||||
[Cache Layer\n(ETag/Last-Modified)] as Cache
|
||||
}
|
||||
|
||||
package "External Services" {
|
||||
[Google AdSense] as AdSense
|
||||
[Analytics\n(opt-in)] as Analytics
|
||||
}
|
||||
|
||||
User --> Frontend : "Visit /"
|
||||
Frontend --> LandingCtrl : "HTTP GET /"
|
||||
LandingCtrl --> StatsAPI : "Fetch download count,\ntool count"
|
||||
LandingCtrl --> ToolsAPI : "Fetch popular tools"
|
||||
LandingCtrl --> AnnouncementsAPI : "Fetch latest announcements\n(optional)"
|
||||
|
||||
StatsAPI --> DB : "Read aggregated stats"
|
||||
ToolsAPI --> DB : "Read tools sorted\nby downloads"
|
||||
AnnouncementsAPI --> DB : "Read announcements"
|
||||
|
||||
DB --> Cache : "Set ETag/Last-Modified"
|
||||
Cache --> StatsAPI : "Cached response"
|
||||
Cache --> ToolsAPI : "Cached response"
|
||||
|
||||
LandingCtrl --> Jinja : "Render template\nwith data"
|
||||
Jinja --> Frontend : "Server-rendered HTML"
|
||||
|
||||
Frontend --> StaticAssets : "Load CSS, JS, images"
|
||||
StaticAssets --> Frontend : "Cached assets"
|
||||
|
||||
Frontend --> AdSense : "Load ad script\n(after consent)"
|
||||
Frontend --> Analytics : "Send page view\n(after consent)"
|
||||
|
||||
Frontend --> SW : "Cache for offline\n(future PWA)"
|
||||
|
||||
note right of LandingCtrl
|
||||
**Critical Path:**
|
||||
1. SSR hero section (no API calls)
|
||||
2. Inline critical CSS
|
||||
3. Lazy load below-fold content
|
||||
4. Defer ad scripts
|
||||
|
||||
**Performance Targets:**
|
||||
- FCP: <1.5s
|
||||
- TTI: <3s
|
||||
- Page weight: <500KB
|
||||
end note
|
||||
|
||||
note right of Cache
|
||||
**Caching Strategy:**
|
||||
- Stats: 5 min TTL
|
||||
- Tools: 5 min TTL
|
||||
- Static assets: 24h TTL
|
||||
- HTML: ETag-based
|
||||
end note
|
||||
|
||||
note bottom of AdSense
|
||||
**Ad Placement:**
|
||||
- Optional footer banner only
|
||||
- Lazy-loaded after content
|
||||
- Requires user consent
|
||||
- Fallback: hide on failure
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,87 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
skinparam componentStyle rectangle
|
||||
|
||||
title SmartTools Registry - Resolution & Caching Architecture
|
||||
|
||||
actor User
|
||||
box "Local Environment" #LightBlue
|
||||
participant "CLI" as CLI
|
||||
participant "Local\nTools" as Local
|
||||
participant "Global\nTools" as Global
|
||||
participant "Cache" as Cache
|
||||
end box
|
||||
|
||||
box "Registry Infrastructure" #LightGreen
|
||||
participant "API\nServer" as API
|
||||
database "SQLite\nDB" as DB
|
||||
participant "Gitea\nRepo" as Repo
|
||||
end box
|
||||
|
||||
User -> CLI: smarttools install summarize
|
||||
|
||||
== Resolution Order ==
|
||||
CLI -> Local: Check ./smarttools/summarize/
|
||||
Local --> CLI: Not found
|
||||
|
||||
CLI -> Global: Check ~/.smarttools/summarize/
|
||||
Global --> CLI: Not found
|
||||
|
||||
CLI -> Cache: Check cached registry index
|
||||
Cache --> CLI: Found (age: 2 min)
|
||||
|
||||
CLI -> API: GET /tools/rob/summarize
|
||||
API -> DB: Query tool + version
|
||||
DB --> API: Tool metadata + YAML
|
||||
API --> CLI: 200 OK + ETag + max-age=300
|
||||
|
||||
CLI -> Cache: Update cache entry
|
||||
CLI -> Global: Write config.yaml
|
||||
CLI -> Global: Generate wrapper script
|
||||
CLI --> User: Installed rob/summarize v1.2.0
|
||||
|
||||
== Offline Scenario ==
|
||||
User -> CLI: smarttools install translate
|
||||
CLI -> Local: Check local
|
||||
Local --> CLI: Not found
|
||||
CLI -> Global: Check global
|
||||
Global --> CLI: Not found
|
||||
CLI -> Cache: Check cache
|
||||
Cache --> CLI: Found translate v2.0.0
|
||||
CLI -> API: GET /tools/rob/translate
|
||||
API -[#red]-> CLI: Connection timeout
|
||||
CLI -> Cache: Use stale cache (warn user)
|
||||
CLI -> Global: Install from cache
|
||||
CLI --> User: Installed rob/translate v2.0.0\n(warning: from cache, registry unavailable)
|
||||
|
||||
== Publishing Flow ==
|
||||
User -> CLI: smarttools registry publish ./mytool/
|
||||
CLI -> CLI: Validate YAML schema
|
||||
CLI -> API: POST /tools (with token)
|
||||
API -> API: Verify auth token
|
||||
API -> Repo: Create branch\n(mytool-v1.0.0)
|
||||
API -> Repo: Commit tool YAML
|
||||
API -> Repo: Create PR
|
||||
Repo --> API: PR #42 URL
|
||||
API --> CLI: 201 Created\n{"pr_url": "..."}
|
||||
CLI --> User: Tool submitted for review\nPR: https://gitea.brrd.tech/.../pulls/42
|
||||
|
||||
== Webhook Sync ==
|
||||
Repo -> API: POST /webhook/gitea\n(PR merged event + HMAC sig)
|
||||
API -> API: Verify HMAC signature
|
||||
API -> Repo: git pull
|
||||
API -> API: Parse tools/*.yaml
|
||||
API -> DB: BEGIN TRANSACTION
|
||||
API -> DB: INSERT/UPDATE tools
|
||||
API -> DB: REBUILD search_index
|
||||
API -> DB: COMMIT
|
||||
API --> Repo: 200 OK
|
||||
|
||||
note right of DB
|
||||
Cache invalidation:
|
||||
- Clear index.json cache
|
||||
- Next API call regenerates
|
||||
- Clients get fresh data
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,33 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
package "Landing Page" {
|
||||
package Header {
|
||||
package "Logo & Nav" {
|
||||
rectangle "SmartTools Logo" #F0F0F0
|
||||
rectangle Navigation #F0F0F0
|
||||
}
|
||||
}
|
||||
|
||||
package "Hero Section" #FFFFFF {
|
||||
note right: Headline: "Build AI Commands in YAML"\nSubheading: "Unix-style, provider-agnostic, composable"\nCTA: "Browse Registry" (Primary)\nCTA: "Get Started" (Secondary)
|
||||
}
|
||||
|
||||
package "Why SmartTools" #F9FAFB {
|
||||
note right: 3 Pillars with Icons:\n- Easy to Use\n- Powerful\n- Community
|
||||
}
|
||||
|
||||
package "Featured Tools" #FFFFFF {
|
||||
note right: Tool Cards (3 columns):\n- Category badge\n- Tool icon/thumbnail\n- Download count\n- Author\n- Quick install command
|
||||
}
|
||||
|
||||
package "Getting Started" #F9FAFB {
|
||||
note right: Tutorial/Example cards\nLinks to docs, tutorials, examples
|
||||
}
|
||||
|
||||
package Footer #FFFFFF {
|
||||
note right: Links: About | Donate | Forum | Docs\nOptional footer ad (light background)\nNewsletter signup (subtle)
|
||||
}
|
||||
}
|
||||
|
||||
note "Design Notes\n---\nColor Palette:\n- Primary: #0052CC (brand blue)\n- Accent: #06B6D4 (teal for secondaries)\n- Background: #F9FAFB (light gray)\n- Cards: #FFFFFF with subtle shadow\n- Ad zone: #FEF3C7 (light yellow background)\n\nMobile: Single column, nav collapses\nTablet: 2 columns featured tools\nDesktop: 3 columns featured tools" as DesignNotes
|
||||
@enduml
|
||||
@@ -0,0 +1 @@
|
||||
@startuml smarttools-web-ui-final-review\n!theme plain\nskinparam backgroundColor #F9FAFB\nskinparam noteBkgColor #DBEAFE\nskinparam noteTextColor #1F2937\n\npackage \"WEB_UI.md Design System\" {\n node \"Visual Identity\" {\n card \"Color Palette\n Primary: #6366F1\n Secondary: #06B6D4\n Status: Green/Amber/Red\"\n card \"Typography\n Inter + JetBrains Mono\n 6-tier size scale\n 1.6 line-height body\"\n card \"Spacing\n 8px base grid\n 4px-64px tokens\n Consistent gaps\"\n }\n \n node \"Component System\" {\n card \"Buttons\n Primary, Secondary\n Ghost, Danger\n 44×44px min touch\"\n card \"Cards\n Tool, Tutorial\n Contributor\n Consistent shadow/radius\"\n card \"Forms\n Inputs, Selects\n Validation states\n Error handling\"\n }\n \n node \"Content Architecture\" {\n card \"Tier 1: Ad-Supported\n Landing, Docs\n Tutorials, Blog\n Sidebar ads allowed\"\n card \"Tier 2: Ad-Free Registry\n Tool Browse\n Tool Details\n Zero ad placement\"\n card \"Tier 3: Light Community\n Forum, Contributors\n Announcements\n Optional footer ads\"\n }\n \n node \"Technical Standards\" {\n card \"Accessibility\n WCAG 2.1 AA target\n 4.5:1 contrast\n Keyboard nav\"\n card \"Performance\n <1.5s LCP target\n <500KB total size\n Critical path optimized\"\n card \"SEO\n Server-rendered\n Structured data\n Canonical URLs\"\n }\n}\n\npackage \"Implementation Readiness\" {\n node \"Design Completeness\" {\n card \"✅ Hero spec\n ✅ Featured content\n ✅ Responsive rules\n ✅ Component library\"\n card \"✅ Auth/dashboard\n ✅ Error states\n ✅ Ad enforcement\n ✅ Privacy/consent\"\n card \"✅ Phase 7 checklist\n ✅ API endpoints\n ✅ SEO/technical\n ✅ Launch readiness\"\n }\n}\n\nnote right of \"WEB_UI.md Design System\"\n Complete design system enabling\n consistent frontend development\n across all page types\nend note\n\nnote right of \"Implementation Readiness\"\n Production-ready specification\n with detailed task checklist\n and technical requirements\nend note\n\n@enduml
|
||||
@@ -0,0 +1,77 @@
|
||||
@startuml
|
||||
!define ACCENT_COLOR #4A90E2
|
||||
!define ERROR_COLOR #E85D75
|
||||
!define SUCCESS_COLOR #5FC98F
|
||||
!define NEUTRAL_COLOR #8B92A9
|
||||
|
||||
skinparam backgroundColor #FFFFFF
|
||||
skinparam titleFontColor #2C3E50
|
||||
skinparam arrowColor ACCENT_COLOR
|
||||
|
||||
title SmartTools Registry: Visual Design Recommendations
|
||||
|
||||
package "Design Strengths" #E8F4F8 {
|
||||
card "Terminology Table" as str1
|
||||
card "Clear Hierarchy" as str2
|
||||
card "Reference Tables" as str3
|
||||
card "Concrete Examples" as str4
|
||||
}
|
||||
|
||||
package "Enhancement Opportunities" #FFF4E6 {
|
||||
card "Visual Decision Trees" as enh1
|
||||
card "ER Diagram Reference" as enh2
|
||||
card "Sequence Diagrams" as enh3
|
||||
card "Error Flow Charts" as enh4
|
||||
card "Consistent Formatting" as enh5
|
||||
}
|
||||
|
||||
package "Critical Flows Needing Visuals" #FFE8E8 {
|
||||
card "Tool Resolution\n(local → global → registry)" as flow1
|
||||
card "Version Constraint\nMatching Logic" as flow2
|
||||
card "Graceful Degradation\nPaths" as flow3
|
||||
}
|
||||
|
||||
package "Implementation Ready" #E8F5E9 {
|
||||
card "Security Documentation" as imp1
|
||||
card "API Specification" as imp2
|
||||
card "Database Schema" as imp3
|
||||
}
|
||||
|
||||
str1 --> str2
|
||||
str2 --> str3
|
||||
str3 --> str4
|
||||
|
||||
enh1 --> flow1
|
||||
enh1 --> flow2
|
||||
enh1 --> flow3
|
||||
|
||||
enh2 --> imp3
|
||||
enh3 --> flow1
|
||||
enh4 --> flow3
|
||||
|
||||
flow1 --> imp1
|
||||
flow2 --> imp1
|
||||
flow3 --> imp1
|
||||
|
||||
note right of str1
|
||||
Eliminates ambiguity
|
||||
from the start
|
||||
end note
|
||||
|
||||
note right of enh1
|
||||
Would improve clarity
|
||||
for complex logic
|
||||
end note
|
||||
|
||||
note right of flow1
|
||||
Critical user journeys
|
||||
deserve visual representation
|
||||
end note
|
||||
|
||||
note right of imp1
|
||||
Document is ready for
|
||||
development with visual
|
||||
enhancements as complementary
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,56 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
skinparam backgroundColor #ffffff
|
||||
skinparam fontFamily monospaced
|
||||
|
||||
rectangle "SmartTools Website Structure" {
|
||||
rectangle "Tier 1: High-Traffic, Ad-Supported" #e8f4f8 {
|
||||
rectangle "Home/Landing" #c7e9f5
|
||||
rectangle "Tutorials & Docs" #c7e9f5
|
||||
rectangle "Blog/Announcements" #c7e9f5
|
||||
rectangle "Featured Projects" #c7e9f5
|
||||
}
|
||||
|
||||
rectangle "Tier 2: Tool Registry (Ad-Free)" #f0f8e8 {
|
||||
rectangle "Browse Registry" #d4f1c5
|
||||
rectangle "Tool Details" #d4f1c5
|
||||
rectangle "Install Flows" #d4f1c5
|
||||
}
|
||||
|
||||
rectangle "Tier 3: Community (Light Ads)" #f8f4e8 {
|
||||
rectangle "Forum/Discussions" #f5e6cc
|
||||
rectangle "Contributors" #f5e6cc
|
||||
rectangle "Changelog" #f5e6cc
|
||||
}
|
||||
}
|
||||
|
||||
rectangle "Revenue Streams" {
|
||||
rectangle "AdSense" #ffe8e8 {
|
||||
rectangle "Sidebar Ads (300x600)" #ffd4d4
|
||||
rectangle "Footer Ads (728x90)" #ffd4d4
|
||||
rectangle "~$50-200/month" #ff9999
|
||||
}
|
||||
|
||||
rectangle "YouTube" #ffe8e8 {
|
||||
rectangle "Embedded Tutorials" #ffd4d4
|
||||
rectangle "~$100-500/month" #ff9999
|
||||
}
|
||||
|
||||
rectangle "Community" #ffe8e8 {
|
||||
rectangle "Donations/Sponsors" #ffd4d4
|
||||
rectangle "~$250-1500/month" #ff9999
|
||||
}
|
||||
}
|
||||
|
||||
rectangle "Design Principles" {
|
||||
rectangle "Visual Hierarchy" #f5f5f5
|
||||
rectangle "Sparse Ad Placement" #f5f5f5
|
||||
rectangle "Mobile-First (No Ads <768px)" #f5f5f5
|
||||
rectangle "Professional Tone" #f5f5f5
|
||||
}
|
||||
|
||||
Tier1 --> AdSense
|
||||
Tier3 --> Community
|
||||
DesignPrinciples ..> Tier1
|
||||
DesignPrinciples ..> Tier2
|
||||
@enduml
|
||||
@@ -0,0 +1,97 @@
|
||||
@startuml
|
||||
!define RECTANGLE rectangle
|
||||
!define COMPONENT component
|
||||
|
||||
skinparam component {
|
||||
BackgroundColor<<External>> #E6F3FF
|
||||
BackgroundColor<<Internal>> #F0F0F0
|
||||
BackgroundColor<<User>> #E8F5E8
|
||||
BorderColor #333333
|
||||
ArrowColor #333333
|
||||
FontSize 12
|
||||
}
|
||||
|
||||
title SmartTools Registry Architecture
|
||||
|
||||
package "Users" <<User>> {
|
||||
actor "CLI User" as cli_user
|
||||
actor "Web User" as web_user
|
||||
}
|
||||
|
||||
package "Client Interfaces" <<User>> {
|
||||
component "smarttools CLI" as cli
|
||||
note right of cli
|
||||
• registry search
|
||||
• registry install
|
||||
• registry publish
|
||||
• registry browse (TUI)
|
||||
end note
|
||||
|
||||
component "Web UI (future)" as web_ui
|
||||
note right of web_ui
|
||||
• Browse tools
|
||||
• Search
|
||||
• View tool details
|
||||
end note
|
||||
}
|
||||
|
||||
component "REGISTRY API SERVER" as api_server <<Internal>> {
|
||||
rectangle "Flask/FastAPI" as server
|
||||
note right of server
|
||||
Hosted at: registry.smarttools.dev
|
||||
(or gitea.brrd.tech/api/registry)
|
||||
end note
|
||||
|
||||
rectangle "Endpoints" as endpoints
|
||||
endpoints : GET /tools // list all tools
|
||||
endpoints : GET /tools/search?q=... // search tools
|
||||
endpoints : GET /tools/{name} // get tool details
|
||||
endpoints : GET /tools/{name}/download // download tool config
|
||||
endpoints : POST /tools // submit new tool (creates PR)
|
||||
endpoints : GET /categories // list categories
|
||||
endpoints : GET /stats // download counts, popular tools
|
||||
|
||||
rectangle "Internal" as internal
|
||||
internal : POST /webhook/gitea // receives push/merge events
|
||||
internal : Sync job // pulls repo, updates DB
|
||||
}
|
||||
|
||||
component "SQLite Database" as database <<Internal>> {
|
||||
rectangle "Database Schema" as db_schema
|
||||
db_schema : tools table
|
||||
db_schema : categories
|
||||
db_schema : download_stats
|
||||
db_schema : search_index
|
||||
}
|
||||
|
||||
component "Gitea Repository" as gitea_repo <<External>> {
|
||||
rectangle "Repository Structure" as repo_structure
|
||||
repo_structure : gitea.brrd.tech/rob/SmartTools-Registry
|
||||
repo_structure : /tools/
|
||||
repo_structure : ├── summarize.yaml
|
||||
repo_structure : ├── translate.yaml
|
||||
repo_structure : └── code-review.yaml
|
||||
repo_structure : /index.json (auto-generated)
|
||||
repo_structure : /categories.json
|
||||
}
|
||||
|
||||
actor "Tool Publisher" as tool_publisher <<User>> {
|
||||
note right of tool_publisher
|
||||
Gitea account required
|
||||
end note
|
||||
}
|
||||
|
||||
' Connections
|
||||
cli_user --> cli : uses
|
||||
web_user --> web_ui : uses
|
||||
|
||||
cli --> api_server : HTTPS
|
||||
web_ui --> api_server : HTTPS
|
||||
|
||||
api_server --> database : reads/writes
|
||||
api_server --> gitea_repo : syncs with
|
||||
|
||||
tool_publisher --> gitea_repo : submits PR
|
||||
gitea_repo --> api_server : webhook events
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,61 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
skinparam defaultFontName Inter
|
||||
skinparam backgroundColor #f8f9fa
|
||||
|
||||
package "Landing Page Layout" {
|
||||
component "Hero Section" as hero {
|
||||
[Value Prop: AI CLI tools for everyone] as value
|
||||
[Install Snippet (copy button)] as snippet
|
||||
[Primary CTA: Browse Tools] as primary
|
||||
[Secondary CTA: View Docs] as secondary
|
||||
}
|
||||
|
||||
component "Value Proposition Grid" as grid {
|
||||
[Easy to Use\nBeginner-friendly] as easy
|
||||
[Powerful\nAdvanced features] as powerful
|
||||
[Community\nCollaboration] as community
|
||||
}
|
||||
|
||||
component "Featured Tools" as tools {
|
||||
[Tool Card 1] as tool1
|
||||
[Tool Card 2] as tool2
|
||||
[Tool Card 3] as tool3
|
||||
}
|
||||
note right of tools: 6-8 tools grid
|
||||
|
||||
component "Project Showcase" as projects {
|
||||
[Project Card 1] as proj1
|
||||
[Project Card 2] as proj2
|
||||
[Project Card 3] as proj3
|
||||
}
|
||||
note right of projects: Real usage examples
|
||||
|
||||
component "Getting Started Preview" as getting {
|
||||
[Tutorial Links] as tutorials
|
||||
[Quick Start Guide] as guide
|
||||
}
|
||||
|
||||
component "Footer" as footer {
|
||||
[Newsletter Signup] as newsletter
|
||||
[Navigation Links] as nav
|
||||
[Social Links] as social
|
||||
}
|
||||
}
|
||||
|
||||
hero --> grid
|
||||
grid --> tools
|
||||
tools --> projects
|
||||
projects --> getting
|
||||
getting --> footer
|
||||
|
||||
note bottom of hero
|
||||
Mobile: Single column
|
||||
Desktop: Full width hero
|
||||
end note
|
||||
|
||||
note bottom of footer
|
||||
Optional AdSense banner
|
||||
Newsletter: Minimal friction
|
||||
end note
|
||||
@enduml
|
||||
@@ -0,0 +1,89 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
title SmartTools Registry - Frontend Architecture
|
||||
|
||||
package "Web UI (Flask + Jinja + Tailwind)" {
|
||||
[Landing Page]
|
||||
[Tool Browser]
|
||||
[Tool Details]
|
||||
[Search Results]
|
||||
[Publisher Dashboard]
|
||||
[Documentation]
|
||||
}
|
||||
|
||||
package "TUI (Terminal UI)" {
|
||||
[Registry Browse]
|
||||
[Tool Search]
|
||||
[Install Interface]
|
||||
[Progress Indicators]
|
||||
}
|
||||
|
||||
package "CLI Interface" {
|
||||
[Publish Flow]
|
||||
[Install Commands]
|
||||
[Search Commands]
|
||||
[Dependency Resolution]
|
||||
}
|
||||
|
||||
package "Client-side State" {
|
||||
[Search Filters]
|
||||
[Tool Cache]
|
||||
[User Preferences]
|
||||
[Session State]
|
||||
}
|
||||
|
||||
package "Responsive Design" {
|
||||
[Mobile Viewport]
|
||||
[Tablet Layout]
|
||||
[Desktop Experience]
|
||||
}
|
||||
|
||||
' API Connections
|
||||
[Tool Browser] --> [API Endpoints]
|
||||
[Search Results] --> [API Endpoints]
|
||||
[Tool Details] --> [API Endpoints]
|
||||
[Publisher Dashboard] --> [API Endpoints]
|
||||
|
||||
' TUI to API
|
||||
[Registry Browse] --> [API Endpoints]
|
||||
[Tool Search] --> [API Endpoints]
|
||||
[Install Interface] --> [API Endpoints]
|
||||
|
||||
' CLI to API
|
||||
[Publish Flow] --> [API Endpoints]
|
||||
[Install Commands] --> [API Endpoints]
|
||||
[Search Commands] --> [API Endpoints]
|
||||
[Dependency Resolution] --> [API Endpoints]
|
||||
|
||||
' Client State Management
|
||||
[Tool Browser] --> [Tool Cache]
|
||||
[Search Results] --> [Search Filters]
|
||||
[Publisher Dashboard] --> [Session State]
|
||||
|
||||
' Responsive Breakpoints
|
||||
[Mobile Viewport] --> [Tool Browser]
|
||||
[Tablet Layout] --> [Tool Details]
|
||||
[Desktop Experience] --> [Publisher Dashboard]
|
||||
|
||||
note right of [Web UI]
|
||||
- Server-rendered with Jinja2
|
||||
- Tailwind CSS for responsive design
|
||||
- Alpine.js for client interactivity
|
||||
- SEO-optimized pages
|
||||
end note
|
||||
|
||||
note right of [TUI]
|
||||
- urwid or python-newt based
|
||||
- Keyboard navigation (j/k, /, Enter)
|
||||
- Virtual scrolling for large lists
|
||||
- Real-time progress feedback
|
||||
end note
|
||||
|
||||
note right of [CLI Interface]
|
||||
- Progress bars for long operations
|
||||
- Clear error messages with suggestions
|
||||
- Token management and secure storage
|
||||
- Dependency resolution visualization
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,71 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
skinparam backgroundColor #FFFFFF
|
||||
skinparam shadowing false
|
||||
|
||||
title SmartTools Registry Frontend Architecture
|
||||
|
||||
rectangle "Frontend Layer" {
|
||||
rectangle "Web UI (Flask + Jinja)" as web {
|
||||
rectangle "Responsive Design" as responsive
|
||||
rectangle "Progressive Enhancement" as progressive
|
||||
rectangle "WCAG 2.1 AA" as accessibility
|
||||
rectangle "SEO Optimized" as seo
|
||||
}
|
||||
|
||||
rectangle "TUI (urwid/python-newt)" as tui {
|
||||
rectangle "Virtual Scrolling" as virtual
|
||||
rectangle "Keyboard Navigation" as keyboard
|
||||
rectangle "Search Interface" as search
|
||||
rectangle "Progress Indicators" as progress
|
||||
}
|
||||
|
||||
rectangle "CLI Interface" as cli {
|
||||
rectangle "--dry-run Validation" as dryrun
|
||||
rectangle "Progress Feedback" as cli_progress
|
||||
rectangle "Error Handling" as cli_error
|
||||
rectangle "Offline Support" as offline
|
||||
}
|
||||
}
|
||||
|
||||
rectangle "Performance Layer" {
|
||||
rectangle "Client Caching" as client_cache
|
||||
rectangle "ETag Support" as etag
|
||||
rectangle "Async Stats" as async_stats
|
||||
rectangle "Bundle Optimization" as bundle
|
||||
}
|
||||
|
||||
rectangle "User Experience Layer" {
|
||||
rectangle "Loading States" as loading
|
||||
rectangle "Error Boundaries" as error_bounds
|
||||
rectangle "Graceful Degradation" as graceful
|
||||
rectangle "Screen Reader Support" as screen_reader
|
||||
}
|
||||
|
||||
web --> responsive
|
||||
web --> progressive
|
||||
web --> accessibility
|
||||
web --> seo
|
||||
|
||||
tui --> virtual
|
||||
tui --> keyboard
|
||||
tui --> search
|
||||
tui --> progress
|
||||
|
||||
cli --> dryrun
|
||||
cli --> cli_progress
|
||||
cli --> cli_error
|
||||
cli --> offline
|
||||
|
||||
responsive --> client_cache
|
||||
progressive --> etag
|
||||
keyboard --> loading
|
||||
cli_progress --> async_stats
|
||||
accessibility --> screen_reader
|
||||
|
||||
client_cache --> bundle
|
||||
etag --> graceful
|
||||
async_stats --> error_bounds
|
||||
loading --> screen_reader
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,73 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
skinparam monochrome true
|
||||
|
||||
title SmartTools Web UI - Frontend Architecture & Revenue Strategy
|
||||
|
||||
package "Frontend Layers" {
|
||||
[Landing Page] as LP
|
||||
[Tool Browse/Search] as TB
|
||||
[Tool Detail Pages] as TD
|
||||
[Documentation] as DOC
|
||||
[Publisher Dashboard] as PD
|
||||
}
|
||||
|
||||
package "Revenue Components" {
|
||||
[AdSense Integration] as ADS
|
||||
[Content Marketing] as CONTENT
|
||||
[Community Features] as COMM
|
||||
[Premium Features] as PREM
|
||||
}
|
||||
|
||||
package "Technical Stack" {
|
||||
[Flask + Jinja] as BACKEND
|
||||
[Tailwind CSS] as CSS
|
||||
[Alpine.js for Interactivity] as JS
|
||||
[Service Worker] as SW
|
||||
}
|
||||
|
||||
LP --> ADS : Ad placement
|
||||
TB --> ADS : Sidebar ads
|
||||
DOC --> ADS : Between articles
|
||||
|
||||
LP --> CONTENT : Featured tools
|
||||
TB --> CONTENT : Tool showcases
|
||||
DOC --> CONTENT : Tutorials
|
||||
|
||||
TD --> COMM : Tool comments
|
||||
PD --> COMM : User profiles
|
||||
|
||||
ADS --> BACKEND : Ad inventory
|
||||
CONTENT --> BACKEND : CMS integration
|
||||
COMM --> BACKEND : Forum backend
|
||||
PREM --> BACKEND : Subscription logic
|
||||
|
||||
BACKEND --> CSS : Server-rendered templates
|
||||
BACKEND --> JS : Alpine.js sprinkles
|
||||
SW --> BACKEND : Offline caching
|
||||
|
||||
note right of ADS
|
||||
Strategic placement:
|
||||
- Search results between
|
||||
- Tool listing sidebar
|
||||
- Documentation bottom
|
||||
- Mobile responsive units
|
||||
end note
|
||||
|
||||
note right of CONTENT
|
||||
Traffic drivers:
|
||||
- Video tutorials (YouTube)
|
||||
- Written tutorials
|
||||
- Project showcases
|
||||
- Case studies
|
||||
end note
|
||||
|
||||
note right of COMM
|
||||
Engagement:
|
||||
- Tool discussions
|
||||
- User profiles
|
||||
- Contributor badges
|
||||
- Project gallery
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,86 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
skinparam backgroundColor #FFF
|
||||
skinparam handwritten false
|
||||
|
||||
rectangle "Web UI Architecture" {
|
||||
rectangle "Tier 1: Ad-Supported Content" as T1 {
|
||||
[Landing]
|
||||
[Documentation]
|
||||
[Tutorials]
|
||||
[Examples]
|
||||
[Blog/Announcements]
|
||||
}
|
||||
|
||||
rectangle "Tier 2: Ad-Free Registry" as T2 {
|
||||
[Tool Browse/Search]
|
||||
[Tool Details]
|
||||
[Categories]
|
||||
[Install Flows]
|
||||
}
|
||||
|
||||
rectangle "Tier 3: Community (Light Ads)" as T3 {
|
||||
[Forum]
|
||||
[Contributors]
|
||||
[Featured Projects]
|
||||
}
|
||||
|
||||
rectangle "Publisher Dashboard (Auth)" as PD {
|
||||
[Registration/Login]
|
||||
[Tool Management]
|
||||
[Token Management]
|
||||
[Settings]
|
||||
}
|
||||
}
|
||||
|
||||
cloud "Revenue Streams" {
|
||||
[AdSense]
|
||||
[YouTube]
|
||||
[Donations]
|
||||
[Featured Listings]
|
||||
[Premium Tiers]
|
||||
}
|
||||
|
||||
database "Backend" {
|
||||
[Registry API]
|
||||
[Content Pages]
|
||||
[Promotions]
|
||||
[Featured Projects]
|
||||
}
|
||||
|
||||
T1 --> T2 : "Core Registry"
|
||||
T2 --> T3 : "Community"
|
||||
T1 --> PD : "Become Publisher"
|
||||
T2 --> PD : "Manage Tools"
|
||||
|
||||
T1 --> AdSense
|
||||
T1 --> YouTube
|
||||
T1 --> Donations
|
||||
T3 --> Featured Listings
|
||||
PD --> Premium Tiers
|
||||
|
||||
T1 --> [Registry API]
|
||||
T2 --> [Registry API]
|
||||
T3 --> [Registry API]
|
||||
PD --> [Registry API]
|
||||
|
||||
note right of T1
|
||||
Professional documentation
|
||||
Video tutorials
|
||||
Community engagement
|
||||
end note
|
||||
|
||||
note right of T2
|
||||
Ad-free experience
|
||||
Fast performance
|
||||
Developer trust
|
||||
end note
|
||||
|
||||
note right of Revenue Streams
|
||||
Sustainable income
|
||||
Fund project maintenance
|
||||
Enable future AI model hosting
|
||||
Support accessibility goals
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,27 @@
|
||||
@startuml
|
||||
actor "User" as U
|
||||
participant "SmartTools Website" as W
|
||||
participant "Payment Gateway" as P
|
||||
participant "Registry Backend" as B
|
||||
|
||||
U -> W : Navigates to "Donate/Contribute" page
|
||||
W --> U : Displays contribution options (one-time, recurring, tiers)
|
||||
U -> W : Selects contribution option
|
||||
W -> W : Validates input (amount, type)
|
||||
alt Valid Input
|
||||
W -> P : Initiates payment (e.g., Stripe, PayPal)
|
||||
P --> U : Prompts for payment details
|
||||
U -> P : Enters payment details
|
||||
P --> W : Payment confirmation/failure
|
||||
alt Payment Success
|
||||
W -> B : Records contribution
|
||||
B --> W : Confirmation
|
||||
W --> U : Displays "Thank You" message & receipt
|
||||
else Payment Failure
|
||||
W --> U : Displays error message & retry option
|
||||
end
|
||||
else Invalid Input
|
||||
W --> U : Displays validation error
|
||||
end
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1 @@
|
||||
@startuml\nskinparam monochrome true\nskinparam shadowing false\nskinparam handwritten false\n\nactor \"User\" as user\nparticipant \"SmartTools CLI\" as cli\nbox \"Web UI (Flask/Jinja/Tailwind)\" #LightBlue\n participant \"Public Pages (Tier 1)\" as public\n participant \"Registry Pages (Tier 2)\" as registry\n participant \"Community Pages (Tier 3)\" as community\n participant \"Publisher Dashboard\" as dashboard\nend box\nparticipant \"Registry API Server\" as api\nparticipant \"Gitea\" as gitea\nparticipant \"AdSense/Analytics\" as ads\nparticipant \"YouTube\" as youtube\n\nuser -> public: Browse Landing Page (/)\npublic -> ads: Load Ads (if applicable)\npublic -> user: Rendered Landing Page (with ads)\n\nuser -> public: View Docs/Tutorials (/docs/*, /tutorials/*)\npublic -> ads: Load Ads (if applicable)\npublic -> youtube: Embed Video (if present)\npublic -> user: Rendered Content (with ads/videos)\n\nuser -> registry: Browse Tools (/tools, /search)\nregistry -> api: GET /tools, /search\napi --> registry: Tool List/Results\nregistry -> user: Rendered Tool List (NO ADS)\n\nuser -> registry: View Tool Details (/tools/{owner}/{name})\nregistry -> api: GET /tools/{owner}/{name}\napi --> registry: Tool Details\nregistry -> user: Rendered Tool Details (NO ADS)\n\nuser -> community: Visit Forum/Contributors\ncommunity -> ads: Load Light Ads (optional)\ncommunity -> user: Rendered Community Content\n\nuser -> dashboard: Register/Login\ndashboard -> api: POST /register, /login\napi --> dashboard: Auth Token\ndashboard -> user: Access Dashboard\n\nuser -> dashboard: Manage Tools/Tokens\ndashboard -> api: Authenticated API Calls\napi --> dashboard: Data\ndashboard -> user: Rendered Dashboard\n\nuser -> cli: Publish Tool (via CLI)\ncli -> api: POST /tools (authenticated)\napi -> gitea: Create PR\ngitea --> api: PR URL\napi --> cli: PR URL\ncli --> user: PR Confirmation\n\nuser -> public: Donate (/donate)\npublic -> user: Donation Options\n\nuser -> public: View Featured Projects\npublic -> api: GET /featured_projects\napi --> public: Featured Projects Data\npublic -> user: Rendered Featured Projects\n\n@enduml
|
||||
Reference in New Issue
Block a user