High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The SuperClaude Website is a documentation-centric React application designed to serve as the interface for the SuperClaude Framework. It utilizes a static site generation (SSG) approach for metadata combined with dynamic client-side fetching for documentation content. The architecture prioritizes a responsive documentation experience, featuring a hierarchical sidebar, markdown rendering with GitHub-flavored styling, and specialized serverless functions for dynamic data like contributor statistics.
Sources: README.md, src/App.js, src/pages/DocViewerPage.js
Application Structure and Routing
The core of the application is built on React 19 and React Router DOM. The App component serves as the entry point, wrapping the application in a SidebarProvider and ThemeProvider to manage global state. The layout is divided into a persistent Navbar, a contextual Sidebar (visible only on documentation routes), and a main content area that dynamically renders pages based on the URL path.
The diagram shows the component hierarchy and routing structure of the application.
Sources: src/index.js:8-15, src/App.js:18-45
Key Layout Components
| Component | Responsibility | Source |
|---|---|---|
AppContent | Determines main container padding and manages routing logic. | src/App.js:17-33 |
Sidebar | Renders a hierarchical menu for documentation navigation. | src/components/Sidebar.js |
Navbar | Provides global navigation and theme switching. | src/components/Navbar.js |
ErrorBoundary | Catches runtime errors to prevent application crashes. | src/App.js:37 |
Documentation Management System
The documentation system relies on a pre-generated metadata map and a custom hook for asynchronous fetching.
Metadata Generation
A build-time script, generate-docs-map.js, scans the public/docs directory. It organizes files based on a predefined categoryOrder and extracts the H1 title from each markdown file to create src/docs-map.json. This JSON file acts as the single source of truth for the navigation sidebar and document cards.
Sources: scripts/generate-docs-map.js:7-53, src/components/Sidebar.js:7
Dynamic Content Loading
Documentation pages use a specialized hook, useDocumentationLoader, to fetch raw markdown files from the public directory based on route parameters.
The sequence diagram illustrates the flow from a user navigating to a doc page to the final rendering of markdown.
Sources: src/hooks/useDocumentationLoader.js:7-43, src/pages/DocViewerPage.js:25-30
Contributor Tracking System
The application tracks contributors across both the framework and website repositories using a Netlify serverless function.
Contributor Data Flow
- Request: The
ContributorsPagemakes a request to/.netlify/functions/get-contributors. - Aggregation: The function fetches data from the GitHub API for both
SuperClaude_FrameworkandSuperClaude_Website. - Caching: To respect GitHub API rate limits, results are cached in-memory for 12 hours.
- Filtering: Specific bots and maintainers are excluded from the list.
- Enhancement: The function performs secondary fetches to retrieve full names for each login.
Sources: netlify/functions/get-contributors.js:10-98, src/pages/ContributorsPage.js:14-25
UI and Styling Architecture
The project utilizes Tailwind CSS for styling and Framer Motion for animations.
Styling Elements
- Theme Management: A CSS variable-based approach is used for light/dark modes, defined in
src/index.css. - Markdown Styling: The
github-markdown-csspackage is applied to themarkdown-bodyclass to ensure documentation matches the GitHub aesthetic. - Interactive Effects: Components like
GlowingEffectuse themotionlibrary (specificallyanimate) to handle high-performance cursor-tracking animations.
Sources: src/index.css:10-53, src/components/GlowingEffect.js:46-95, tailwind.config.js:8-23
Build and Deployment Pipeline
The project uses npm scripts to automate the documentation preparation before starting or building the application.
| Script | Command | Purpose |
|---|---|---|
prestart | node scripts/fetch-docs.mjs && node scripts/generate-docs-map.js | Fetches external docs and builds the local map before dev. |
prebuild | node scripts/fetch-docs.mjs && node scripts/generate-docs-map.js | Prepares documentation assets for the production build. |
build | react-scripts build | Compiles the React application for production. |
Sources: package.json:34-39
Conclusion
The architecture of the SuperClaude Website effectively decouples documentation content from the application logic. By using a pre-generated docs-map.json for navigation and dynamic fetching for content, the system remains performant and easy to maintain as the documentation library grows. The integration of serverless functions for contributor data ensures the site stays up-to-date without requiring frequent manual rebuilds.