firefrost-gaming/skill-seekers-reference
3
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: sync StarUML diagrams with Grand Unification refactor

Browse Source 
Updated 6 of 21 diagrams to reflect the SkillConverter + ExecutionContext
architecture:

Structural:
- 01 CLICore: Added ExecutionContext singleton, updated CreateCommand
  methods (_build_config, _route_to_scraper, _run_enhancement)
- 02 Scrapers: Replaced IScraper interface with SkillConverter base class,
  added CONVERTER_REGISTRY, removed main() from all 18 converters
- 09 Parsers: Removed 18 scraper-specific parsers (27 → 18 subclasses)

Behavioral:
- 14 Create Pipeline: Rewritten — converter.run() replaces scraper.main(),
  ExecutionContext.initialize() added, enhancement centralized
- 17 MCP Invocation: Path A now uses get_converter() in-process, not subprocess
- UML_ARCHITECTURE.md descriptions updated throughout

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
yusyus
2026-04-08 22:41:43 +03:00
parent c896f8cb37
commit 49f29cbc5a
8 changed files with 5286 additions and 11569 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/UML_ARCHITECTURE.md
View File

@@ -1,10 +1,10 @@
# Skill Seekers Architecture
> Generated 2026-03-22 | StarUML project: `docs/UML/skill_seekers.mdj`
> Updated 2026-04-08 | StarUML project: `docs/UML/skill_seekers.mdj`
## Overview
Skill Seekers converts documentation from 17 source types into production-ready formats for 24+ AI platforms. The architecture follows a layered module design with 8 core modules and 5 utility modules.
Skill Seekers converts documentation from 18 source types into production-ready formats for 24+ AI platforms. The architecture follows a layered module design with 8 core modules and 5 utility modules. All source types are routed through a single `skill-seekers create` command via the `SkillConverter` base class + factory pattern.
## Package Diagram
@@ -32,12 +32,12 @@ Skill Seekers converts documentation from 17 source types into production-ready
### CLICore
![CLICore](UML/exports/01_cli_core.png)
Entry point: `skill-seekers` CLI. `CLIDispatcher` maps subcommands to modules via `COMMAND_MODULES` dict. `CreateCommand` auto-detects source type via `SourceDetector`.
Entry point: `skill-seekers` CLI. `CLIDispatcher` maps subcommands to modules via `COMMAND_MODULES` dict. `CreateCommand` auto-detects source type via `SourceDetector`, initializes `ExecutionContext` singleton (Pydantic model, single source of truth for all config), then calls `get_converter()` → `converter.run()`. Enhancement runs centrally in CreateCommand after the converter completes.
### Scrapers
![Scrapers](UML/exports/02_scrapers.png)
18 scraper classes implementing `IScraper`. Each has a `main()` entry point. Notable: `GitHubScraper` (3-stream fetcher) + `GitHubToSkillConverter` (builder), `UnifiedScraper` (multi-source orchestrator).
18 converter classes inheriting `SkillConverter` base class (Template Method: `run()` → `extract()` → `build_skill()`). Factory: `get_converter(source_type, config)` via `CONVERTER_REGISTRY`. No `main()` entry points — all routing through `CreateCommand`. Notable: `GitHubScraper` (3-stream fetcher) + `GitHubToSkillConverter` (builder), `UnifiedScraper` (multi-source orchestrator).
### Adaptors
![Adaptors](UML/exports/03_adaptors.png)
@@ -74,7 +74,7 @@ Two enhancement hierarchies: `AIEnhancer` (API mode, multi-provider via `AgentCl
### Parsers
![Parsers](UML/exports/09_parsers.png)
`SubcommandParser` ABC with 27 subclasses -- one per CLI subcommand (Create, Scrape, GitHub, PDF, Word, EPUB, Video, Unified, Analyze, Enhance, Package, Upload, Jupyter, HTML, OpenAPI, AsciiDoc, Pptx, RSS, ManPage, Confluence, Notion, Chat, Config, Estimate, Install, Stream, Quality, SyncConfig).
`SubcommandParser` ABC with 18 subclasses — individual scraper parsers removed after Grand Unification (all source types route through `CreateParser`). Remaining: Create, Doctor, Config, Enhance, EnhanceStatus, Package, Upload, Estimate, Install, InstallAgent, TestExamples, Resume, Quality, Workflows, SyncConfig, Stream, Update, Multilang.
### Storage
![Storage](UML/exports/10_storage.png)
@@ -103,16 +103,18 @@ Two enhancement hierarchies: `AIEnhancer` (API mode, multi-provider via `AgentCl
| Strategy + Factory | Adaptors | `SkillAdaptor` ABC + `get_adaptor()` factory + 20+ implementations |
| Strategy + Factory | Storage | `BaseStorageAdaptor` ABC + S3/GCS/Azure |
| Strategy + Factory | Embedding | `EmbeddingProvider` ABC + OpenAI/Local |
| Template Method + Factory | Scrapers | `SkillConverter` base + `get_converter()` factory + 18 converter subclasses |
| Singleton | Configuration | `ExecutionContext` Pydantic model — single source of truth for all config |
| Command | CLI | `CLIDispatcher` + `COMMAND_MODULES` lazy dispatch |
| Template Method | Pattern Detection | `BasePatternDetector` + 10 GoF detectors |
| Template Method | Parsers | `SubcommandParser` + 27 subclasses |
| Template Method | Parsers | `SubcommandParser` + 18 subclasses |
## Behavioral Diagrams
### Create Pipeline Sequence
![Create Pipeline](UML/exports/14_create_pipeline_sequence.png)
`CreateCommand` is a dispatcher, not a pipeline orchestrator. Flow: User → `execute()` → `SourceDetector.detect(source)` → `validate_source()` → `_validate_arguments()` → `_route_to_scraper()` → `scraper.main(argv)`. The 5 phases (scrape, build_skill, enhance, package, upload) all happen *inside* each scraper's `main()` — CreateCommand only sees the exit code.
`CreateCommand` is now the pipeline orchestrator. Flow: User → `execute()` → `SourceDetector.detect(source)` → `validate_source()` → `ExecutionContext.initialize()` → `_validate_arguments()` → `get_converter(type, config)` → `converter.run()` (extract + build_skill) → `_run_enhancement(ctx)` → `_run_workflows()`. Enhancement is centralized in CreateCommand, not inside each converter.
### GitHub Unified Flow + C3.x
![GitHub Unified](UML/exports/15_github_unified_sequence.png)
@@ -127,7 +129,7 @@ Activity diagram showing `source_detector.py` decision tree in correct code orde
### MCP Tool Invocation
![MCP Invocation](UML/exports/17_mcp_invocation_sequence.png)
MCP Client (Claude Code/Cursor) → FastMCPServer (stdio/HTTP) with two invocation paths: **Path A** (scraping tools) uses `subprocess.run(["skill-seekers", ...])`, **Path B** (packaging/config tools) uses direct Python imports (`get_adaptor()`, `sync_config()`). Both return TextContent → JSON-RPC.
MCP Client (Claude Code/Cursor) → FastMCPServer (stdio/HTTP) with two invocation paths: **Path A** (scraping tools) uses `get_converter(type, config).run()` in-process via `_run_converter()` helper, **Path B** (packaging/config tools) uses direct Python imports (`get_adaptor()`, `sync_config()`). Both return TextContent → JSON-RPC.
### Enhancement Pipeline
![Enhancement Pipeline](UML/exports/18_enhancement_activity.png)
@@ -137,7 +139,7 @@ MCP Client (Claude Code/Cursor) → FastMCPServer (stdio/HTTP) with two invocati
### Runtime Components
![Runtime Components](UML/exports/19_runtime_components.png)
Component diagram with corrected runtime dependencies. Key flows: `CLI Core` dispatches to `Scrapers` (via `scraper.main(argv)`) and to `Adaptors` (via package/upload commands). `Scrapers` call `Codebase Analysis` via `analyze_codebase(enhance_level)`. `Codebase Analysis` uses `C3.x Classes` internally and `Enhancement` when level ≥ 2. `MCP Server` reaches `Scrapers` via subprocess and `Adaptors` via direct import. `Scrapers` optionally use `Browser Renderer (Playwright)` via `render_page()` when `--browser` flag is set for JavaScript SPA sites.
Component diagram with runtime dependencies. Key flows: `CLI Core` dispatches to `Scrapers` via `get_converter()` → `converter.run()` (in-process, no subprocess). `Scrapers` call `Codebase Analysis` via `analyze_codebase(enhance_level)`. `Codebase Analysis` uses `C3.x Classes` internally and `Enhancement` when level ≥ 2. `MCP Server` reaches `Scrapers` via `get_converter()` in-process and `Adaptors` via direct import. `Scrapers` optionally use `Browser Renderer (Playwright)` via `render_page()` when `--browser` flag is set for JavaScript SPA sites.
### Browser Rendering Flow
![Browser Rendering](UML/exports/20_browser_rendering_sequence.png)