diff --git a/DOCUMENTOR-GUIDE.md b/DOCUMENTOR-GUIDE.md new file mode 100644 index 0000000..2a66f11 --- /dev/null +++ b/DOCUMENTOR-GUIDE.md @@ -0,0 +1,156 @@ +# Documentation Platform - Visual Overview + +```text +┌─────────────────────────────────────────────────────────────────────────────┐ +│ DOCUMENTATION REPOSITORY STRUCTURE │ +└─────────────────────────────────────────────────────────────────────────────┘ + +📁 Repository Root +│ +├── 📁 resources/ +│ │ +│ ├── 📁 edp-likec4/ ← Platform Architecture +│ │ ├── documentation-platform.c4 (Models for EDP systems) +│ │ ├── views.c4 +│ │ ├── models/ +│ │ └── views/ +│ │ +│ └── 📁 doc-likec4/ ← Documentation Platform Architecture +│ ├── documentation-platform.c4 (Models for this doc system) +│ ├── views.c4 +│ ├── likec4.config.json +│ ├── package.json +│ └── README.md +│ +├── 📁 content/en/docs/ +│ │ +│ ├── 📁 architecture/ ← Platform Architecture Docs +│ │ ├── highlevelarch.md +│ │ └── setup.md +│ │ +│ └── 📁 documentation/ ← Documentation About Documentation +│ ├── _index.md (Overview for Documentors) +│ ├── local-development.md (How to work locally) +│ ├── testing.md (Quality assurance) +│ ├── cicd.md (CI/CD pipeline) +│ ├── publishing.md (Deployment to edge) +│ └── quick-reference.md (Cheat sheet) +│ +├── 📄 Taskfile.yml ← Build Automation +├── 📄 .github/workflows/test.yml ← CI Pipeline +├── 📄 k8s-deployment.yaml ← Kubernetes Config +├── 📄 edgeconnectdeployment.yaml ← Edge Deployment Config +├── 📄 Dockerfile ← Container Definition +└── 📄 README-ARCHITECTURE.md ← This Overview + + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ DOCUMENTOR WORKFLOW │ +└─────────────────────────────────────────────────────────────────────────────┘ + + 👤 Documentor + │ + ├──> 1. Write Content + │ └── content/en/docs/**/*.md + │ + ├──> 2. Create Architecture Models + │ └── resources/doc-likec4/*.c4 + │ resources/edp-likec4/*.c4 + │ + ├──> 3. Local Development + │ └── task serve + │ http://localhost:1313 + │ + ├──> 4. Test Locally + │ └── task test:quick + │ - Build validation + │ - Markdown lint + │ + ├──> 5. Commit & Push + │ └── git push origin feature-branch + │ + └──> 6. CI/CD Pipeline + ├── GitHub Actions + │ ├── Build Test + │ ├── Markdown Lint + │ ├── HTML Validation + │ └── Link Checking + │ + ├── Container Build + │ └── Docker Image + │ + └── Edge Deployment + └── Kubernetes on Munich Cloudlet + └── http:// + + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ARCHITECTURE VISUALIZATION │ +└─────────────────────────────────────────────────────────────────────────────┘ + +Two Separate LikeC4 Projects: + +┌──────────────────────────────┐ ┌──────────────────────────────┐ +│ resources/edp-likec4/ │ │ resources/doc-likec4/ │ +│ ───────────────────── │ │ ───────────────────── │ +│ │ │ │ +│ Platform Architecture │ │ Documentation Platform │ +│ ──────────────────── │ │ ──────────────────── │ +│ │ │ │ +│ • Systems │ │ • Hugo/Docsy │ +│ • Services │ │ • LikeC4 Integration │ +│ • Infrastructure │ │ • Taskfile │ +│ • Deployment Environments │ │ • GitHub Actions │ +│ │ │ • Edge Deployment │ +│ What we BUILD │ │ How we DOCUMENT │ +│ │ │ │ +└──────────────────────────────┘ └──────────────────────────────┘ + │ │ + │ │ + ▼ ▼ + content/en/docs/ content/en/docs/ + architecture/ documentation/ + + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ QUICK START │ +└─────────────────────────────────────────────────────────────────────────────┘ + +For New Documentors: + +1. 📖 Read the Guide + → Open: content/en/docs/documentation/_index.md + → Or browse: http://localhost:1313/docs/documentation/ + +2. 🚀 Start Development + $ task serve + +3. 📊 View Architecture + $ cd resources/doc-likec4 + $ npm install + $ npm start + → Opens: http://localhost:5173 + +4. ✅ Test Your Changes + $ task test:quick + +5. 📚 Reference + → Quick Reference: content/en/docs/documentation/quick-reference.md + + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ AVAILABLE VIEWS │ +└─────────────────────────────────────────────────────────────────────────────┘ + +In resources/doc-likec4/views.c4: + +• overview → Complete system overview +• localDevelopment → Documentor workflow with Taskfile +• cicdPipeline → Automated testing via GitHub Actions +• deploymentFlow → Edge deployment process +• fullWorkflow → End-to-end content → production +• testingCapabilities → All automated tests + +Embed in Markdown: +{{< likec4-view view="overview" project="documentation-platform" >}} +``` diff --git a/README-ARCHITECTURE.md b/README-ARCHITECTURE.md new file mode 100644 index 0000000..4efb435 --- /dev/null +++ b/README-ARCHITECTURE.md @@ -0,0 +1,92 @@ +# Documentation Platform - Overview + +This repository contains two distinct LikeC4 architecture documentation projects: + +## 📁 Structure + +### `resources/edp-likec4/` + +**Enterprise Developer Platform (EDP) Architecture** + +Contains architecture models for the platform itself - the systems, services, and infrastructure that make up the EDP. + +**Purpose:** Document what we build + +### `resources/doc-likec4/` + +**Documentation Platform Architecture** + +Contains architecture models that explain how this documentation system works - the Hugo/Docsy setup, CI/CD pipeline, and deployment process. + +**Purpose:** Document how we document (meta-documentation) + +## 🎯 For New Documentors + +If you're new to the documentor role and want to understand the documentation platform: + +1. **Read the documentation about documentation:** + → `content/en/docs/documentation/` + +2. **View the architecture diagrams:** + → The documentation pages embed interactive LikeC4 diagrams + +3. **Key sections:** + - [Overview](content/en/docs/documentation/_index.md) - What is a documentor? + - [Local Development](content/en/docs/documentation/local-development.md) - Get started + - [Testing](content/en/docs/documentation/testing.md) - Quality assurance + - [CI/CD](content/en/docs/documentation/cicd.md) - Automated pipeline + - [Publishing](content/en/docs/documentation/publishing.md) - Deployment to edge + +## 🚀 Quick Start + +```bash +# Start development server +task serve + +# Run tests +task test:quick + +# View architecture models +cd resources/doc-likec4 +npm install +npm start +``` + +## 📊 Architecture Views + +The documentation platform is visualized with these views: + +- **Overview** - Complete system overview +- **Local Development** - Documentor workflow +- **CI/CD Pipeline** - Automated testing +- **Deployment Flow** - Edge deployment process +- **Full Workflow** - End-to-end journey +- **Testing Capabilities** - Quality assurance + +## 🔗 Related Files + +- `Taskfile.yml` - Automation for local development and CI +- `.github/workflows/test.yml` - GitHub Actions CI pipeline +- `k8s-deployment.yaml` - Kubernetes deployment manifest +- `edgeconnectdeployment.yaml` - Edge Connect configuration +- `Dockerfile` - Container image definition + +## 📚 Documentation + +The documentation is built with: + +- **Hugo** - Static site generator +- **Docsy** - Documentation theme +- **LikeC4** - Architecture visualization +- **Task** - Build automation +- **GitHub Actions** - CI/CD +- **Edge Connect** - Deployment platform + +## 🎓 Learn More + +For complete information, browse to the documentation section after starting the server: + +```bash +task serve +# Then open: http://localhost:1313/docs/documentation/ +```