From 073e6b5a546ced99af66f2ff9b35fb0d39c53166 Mon Sep 17 00:00:00 2001 From: yusyus Date: Sun, 22 Mar 2026 12:33:56 +0300 Subject: [PATCH] docs: add architecture references to README.md and CONTRIBUTING.md - README: Add Architecture section with package overview diagram, module table, and links to UML docs - README: Add Architecture subsection to Documentation with links to diagrams, HTML API reference, and StarUML project - CONTRIBUTING: Add UML Architecture subsection with design patterns documented and guidance to keep UML in sync with code changes Co-Authored-By: Claude Opus 4.6 (1M context) --- CONTRIBUTING.md | 18 ++++++++++++++++++ README.md | 27 +++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8902d36..555d046 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -481,6 +481,24 @@ Skill_Seekers/ **Scraper pattern (17 source types):** Each source type has `cli/_scraper.py` (with `ToSkillConverter` class + `main()`), `arguments/.py`, and `parsers/_parser.py`. Register new types in: `parsers/__init__.py` PARSERS list, `main.py` COMMAND_MODULES dict, `config_validator.py` VALID_SOURCE_TYPES set. +### UML Architecture + +Full UML class diagrams are maintained in StarUML and synced from source code: + +- **[Docs/Architecture.md](Docs/Architecture.md)** - Overview with embedded PNG diagrams +- **[Docs/UML/skill_seekers.mdj](Docs/UML/skill_seekers.mdj)** - StarUML project (open with [StarUML](https://staruml.io/)) +- **[Docs/UML/exports/](Docs/UML/exports/)** - 14 PNG exports (package overview + 13 class diagrams) +- **[Docs/UML/html/](Docs/UML/html/index.html/index.html)** - HTML API reference + +**Key design patterns documented in UML:** +- Strategy + Factory in Adaptors (SkillAdaptor ABC + 20+ implementations) +- Strategy + Factory in Storage (BaseStorageAdaptor + S3/GCS/Azure) +- Template Method in Parsers (SubcommandParser + 28 subclasses) +- Template Method in Analysis (BasePatternDetector + 10 GoF detectors) +- Command pattern in CLI (CLIDispatcher + COMMAND_MODULES lazy dispatch) + +When adding new classes or modules, please update the corresponding UML diagram to keep architecture docs in sync. + --- ## Release Process diff --git a/README.md b/README.md index 036a25c..5493b1c 100644 --- a/README.md +++ b/README.md @@ -894,6 +894,27 @@ graph LR 3. **Enhance**: AI analyzes docs and creates comprehensive SKILL.md with examples 4. **Package**: Bundles everything into a Claude-ready `.zip` file +## Architecture + +The system is organized into **8 core modules** and **5 utility modules** (~200 classes total): + +![Package Overview](Docs/UML/exports/00_package_overview.png) + +| Module | Purpose | Key Classes | +|--------|---------|-------------| +| **CLICore** | Git-style command dispatcher | `CLIDispatcher`, `SourceDetector`, `CreateCommand` | +| **Scrapers** | 17 source-type extractors | `DocToSkillConverter`, `GitHubScraper`, `UnifiedScraper` | +| **Adaptors** | 20+ output platform formats | `SkillAdaptor` (ABC), `ClaudeAdaptor`, `LangChainAdaptor` | +| **Analysis** | C3.x codebase analysis pipeline | `UnifiedCodebaseAnalyzer`, `PatternRecognizer`, 10 GoF detectors | +| **Enhancement** | AI-powered skill improvement | `AIEnhancer`, `UnifiedEnhancer`, `WorkflowEngine` | +| **Packaging** | Package, upload, install skills | `PackageSkill`, `InstallAgent` | +| **MCP** | FastMCP server (34 tools) | `SkillSeekerMCPServer`, 8 tool modules | +| **Sync** | Doc change detection | `ChangeDetector`, `SyncMonitor`, `Notifier` | + +Utility modules: **Parsers** (28 CLI parsers), **Storage** (S3/GCS/Azure), **Embedding** (multi-provider vectors), **Benchmark** (performance), **Utilities** (16 shared helpers). + +Full UML diagrams: **[Docs/Architecture.md](Docs/Architecture.md)** | StarUML project: `Docs/UML/skill_seekers.mdj` | HTML API reference: `Docs/UML/html/` + ## 📋 Prerequisites **Before you start, make sure you have:** @@ -1161,6 +1182,12 @@ skill-seekers config --github - **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions - **[docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md)** - One-page cheat sheet +### Architecture +- **[Docs/Architecture.md](Docs/Architecture.md)** - UML architecture overview with 14 diagrams +- **[Docs/UML/exports/](Docs/UML/exports/)** - PNG diagram exports (package overview + 13 class diagrams) +- **[Docs/UML/html/](Docs/UML/html/index.html/index.html)** - Full HTML API reference (all classes, operations, attributes) +- **[Docs/UML/skill_seekers.mdj](Docs/UML/skill_seekers.mdj)** - StarUML project file (open with [StarUML](https://staruml.io/)) + ### Guides - **[docs/LARGE_DOCUMENTATION.md](docs/LARGE_DOCUMENTATION.md)** - Handle 10K-40K+ page docs - **[ASYNC_SUPPORT.md](ASYNC_SUPPORT.md)** - Async mode guide (2-3x faster scraping)