{"id":34534421,"url":"https://github.com/sgort/iou-architectuur","last_synced_at":"2026-05-27T01:05:07.068Z","repository":{"id":324065646,"uuid":"1095833388","full_name":"sgort/iou-architectuur","owner":"sgort","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-13T06:50:15.000Z","size":30490,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-13T08:34:06.638Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgort.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-13T15:21:47.000Z","updated_at":"2026-05-13T06:50:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sgort/iou-architectuur","commit_stats":null,"previous_names":["sgort/iou-architectuur"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sgort/iou-architectuur","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgort%2Fiou-architectuur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgort%2Fiou-architectuur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgort%2Fiou-architectuur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgort%2Fiou-architectuur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgort","download_url":"https://codeload.github.com/sgort/iou-architectuur/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgort%2Fiou-architectuur/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33545459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T05:58:02.058Z","updated_at":"2026-05-27T01:05:07.050Z","avatar_url":"https://github.com/sgort.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IOU Architecture Documentation\n\n[![MkDocs](https://img.shields.io/badge/docs-MkDocs-blue)](https://www.mkdocs.org/)\n[![Material for MkDocs](https://img.shields.io/badge/theme-Material-00897B)](https://squidfunk.github.io/mkdocs-material/)\n[![License](https://img.shields.io/badge/license-EUPL--1.2-blue)](LICENSE)\n\n\u003e Comprehensive documentation for the IOU Architecture Framework and RONL ecosystem, deployed to [iou-architectuur.open-regels.nl](https://iou-architectuur.open-regels.nl)\n\n## 📋 Overview\n\nThis repository contains the source files for the IOU Architecture documentation website. The site provides comprehensive technical documentation for:\n\n- **IOU Architecture Framework** - Information architecture for IOU\n- **RONL Business API** - Business API layer for Dutch government services\n- **CPSV Editor** - React application for creating CPSV-AP compliant RDF/Turtle files\n- **Linked Data Explorer** - SPARQL visualization and DMN orchestration tool\n- **Shared Backend** - Node.js API providing TriplyDB and Operaton integration\n\n## 🌐 Live Documentation\n\n**Production**: [https://iou-architectuur.open-regels.nl](https://iou-architectuur.open-regels.nl)\n\n## 🏗️ Technology Stack\n\n| Component | Technology | Version |\n|-----------|------------|---------|\n| **Static Site Generator** | MkDocs | 1.5+ |\n| **Theme** | Material for MkDocs | 9.5+ |\n| **Internationalization** | mkdocs-static-i18n | 1.2+ |\n| **Version Control** | Git | - |\n| **Hosting** | Azure Static Web Apps | - |\n| **CI/CD** | GitHub Actions | - |\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.10 or higher\n- Git\n- A text editor (VS Code recommended)\n\n### Local Development Setup\n\n```bash\n# 1. Clone the repository\ngit clone https://git.open-regels.nl/showcases/iou-architectuur.git\ncd iou-architectuur\n\n# 2. Create virtual environment\npython -m venv venv\n\n# 3. Activate virtual environment\n# Linux/macOS:\nsource venv/bin/activate\n# Windows:\nsource venv/Scripts/activate\n\n# 4. Install dependencies\npip install -r requirements.txt\n\n# 5. Start development server\nmkdocs serve\n```\n\nThe site will be available at: **http://127.0.0.1:8000**\n\nThe development server features **hot reload** - changes to markdown files are reflected immediately in your browser.\n\n## 📂 Repository Structure\n\n```\niou-architectuur/\n├── docs/\n│   ├── en/                          # English documentation\n│   │   ├── index.md                 # Homepage\n│   │   ├── cpsv-editor/             # CPSV Editor docs\n│   │   ├── linked-data-explorer/    # Linked Data Explorer docs\n│   │   ├── ronl-business-api/       # RONL Business API docs\n│   │   ├── shared-backend/          # Shared Backend docs\n│   │   ├── contributing/            # Contribution guidelines\n│   │   ├── assets/                  # Images and diagrams\n│   │   └── stylesheets/             # Custom CSS\n│   ├── nl/                          # Dutch documentation (translations)\n│   │   └── [mirrors en/ structure]\n│   └── includes/\n│       └── abbreviations.md         # Common abbreviations\n├── mkdocs.yml                       # MkDocs configuration\n├── requirements.txt                 # Python dependencies\n├── .gitignore                       # Git ignore rules\n├── staticwebapp.config.json         # Azure SWA configuration\n├── .github/workflows/               # GitHub Actions workflows\n└── README.md                        # This file\n```\n\n## ✍️ Content Management\n\n### Adding New Pages\n\n1. Create a markdown file in `docs/en/[section]/`\n2. Add the page to `mkdocs.yml` navigation:\n\n```yaml\nnav:\n  - Section Name:\n    - New Page: section/new-page.md\n```\n\n3. Create Dutch translation in `docs/nl/[section]/`\n4. Test locally with `mkdocs serve`\n\n### Markdown Features\n\nThe documentation supports:\n\n- **Admonitions**: Info boxes, warnings, notes\n- **Code blocks**: Syntax highlighting for 100+ languages\n- **Mermaid diagrams**: Flowcharts, sequence diagrams, etc.\n- **Tables**: GitHub-flavored markdown tables\n- **Cross-references**: Internal links between pages\n- **Emoji**: `:material-check:` renders as ✅\n\n**Example:**\n\n```markdown\n!!! note \"Important\"\n    This is an important note.\n\n```python\ndef hello_world():\n    print(\"Hello, World!\")\n```\n\n[Link to another page](other-page.md)\n```\n\n### Images\n\nPlace images in `docs/en/assets/` and reference them:\n\n```markdown\n![Description](../assets/image.png)\n```\n\nImages are shared between English and Dutch versions (symlinked in `docs/nl/assets/`).\n\n## 🌍 Multilingual Support\n\nThe site supports English (primary) and Dutch (translation).\n\n### File Structure\n\n```\ndocs/\n├── en/\n│   └── section/\n│       └── page.md          # English content\n└── nl/\n    └── section/\n        └── page.md          # Dutch translation\n```\n\n### Translation Workflow\n\n1. Write content in English first (`docs/en/`)\n2. Create Dutch translation (`docs/nl/`)\n3. Keep folder structure identical\n4. Use English filenames (e.g., `overview.md` not `overzicht.md`)\n\n### Language Switcher\n\nThe language switcher in the top-right corner allows users to toggle between English and Dutch versions of the same page.\n\n## 🔨 Building the Site\n\n### Development Build\n\n```bash\nmkdocs serve\n```\n\n- Includes live reload\n- Draft content visible\n- Fast build times\n\n### Production Build\n\n```bash\nmkdocs build\n```\n\n- Outputs to `site/` directory\n- Minified assets\n- Optimized for deployment\n- Strict mode enabled (fails on warnings)\n\n### Testing the Build\n\n```bash\n# Build and check for warnings\nmkdocs build --strict\n\n# Serve the production build\nmkdocs serve --strict\n```\n\n## 🚢 Deployment\n\n### Automatic Deployment (Recommended)\n\nEvery push to the `main` branch automatically deploys to production via GitHub Actions:\n\n```bash\ngit add .\ngit commit -m \"docs: update content\"\ngit push origin main\n```\n\n**Pipeline Steps:**\n1. ✅ Install Python dependencies\n2. ✅ Build site with MkDocs\n3. ✅ Deploy to Azure Static Web Apps\n4. ✅ Invalidate CDN cache\n\n**Deployment time**: ~2-3 minutes\n\n### Manual Deployment\n\nIf needed, you can deploy manually using Azure CLI:\n\n```bash\n# Build locally\nmkdocs build\n\n# Deploy to Azure\naz staticwebapp upload \\\n  --name iou-architectuur \\\n  --resource-group rg-iou-architectuur \\\n  --source site/ \\\n  --token $AZURE_STATIC_WEB_APPS_API_TOKEN\n```\n\n## 🛠️ Development Tools\n\n### Useful Scripts\n\n```bash\n# Check for broken links (after manual edits)\n./find-broken-links.sh report\n\n# Clean up old files\n./cleanup-ronl-setup.sh\n```\n\n### Recommended VS Code Extensions\n\n- **Python** - Python language support\n- **Markdown All in One** - Markdown editing tools\n- **markdownlint** - Markdown linting\n- **Code Spell Checker** - Spell checking for documentation\n\n### Linting\n\n```bash\n# Markdown linting\nmarkdownlint docs/**/*.md\n\n# Link checking\nmkdocs build --strict\n```\n\n## 🎨 Styling\n\n### Custom CSS\n\nCustom styles are defined in `docs/stylesheets/extra.css` and follow the NL Design System:\n\n- **Primary color**: `#154273` (Rijksoverheid blue)\n- **Accent color**: `#e17000` (Orange)\n- **Status colors**: Green, blue, orange, red for compliance states\n\n### Theme Configuration\n\nTheme settings in `mkdocs.yml`:\n\n```yaml\ntheme:\n  name: material\n  palette:\n    - scheme: default\n      primary: blue\n      accent: orange\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](docs/en/contributing/index.md) for details.\n\n### Quick Contribution Guide\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Make your changes\n4. Test locally: `mkdocs serve`\n5. Commit with clear messages: `git commit -m \"docs: add XYZ section\"`\n6. Push to your fork: `git push origin feature/my-feature`\n7. Open a merge request\n\n### Commit Message Convention\n\n```\ndocs: add new section about X\nfix: correct typo in Y\nfeat: add multilingual support for Z\n```\n\n## 📊 Site Analytics\n\nThe site uses Azure Static Web Apps built-in analytics:\n\n- Page views\n- Unique visitors\n- Geographic distribution\n- Referral sources\n\nAccess analytics in the Azure Portal.\n\n## 🔒 Security\n\n### HTTPS\n\n- Automatic SSL certificate via Let's Encrypt\n- Forced HTTPS redirects\n- Certificate auto-renewal\n\n### Content Security Policy\n\nConfigured in `staticwebapp.config.json`:\n\n```json\n{\n  \"globalHeaders\": {\n    \"Content-Security-Policy\": \"default-src 'self'; ...\",\n    \"X-Content-Type-Options\": \"nosniff\",\n    \"X-Frame-Options\": \"DENY\"\n  }\n}\n```\n\n## 🐛 Troubleshooting\n\n### Build Fails\n\n**Check Python version:**\n```bash\npython --version  # Must be 3.10+\n```\n\n**Reinstall dependencies:**\n```bash\npip install --upgrade -r requirements.txt\n```\n\n### Links Not Working\n\n**Check file paths:**\n- Use relative paths: `../other-page.md`\n- Check file actually exists\n- Ensure proper casing (case-sensitive on Linux)\n\n### Images Not Displaying\n\n**Verify image path:**\n```bash\nls -la docs/en/assets/your-image.png\n```\n\n**Use correct relative path from the markdown file.**\n\n### Dutch Pages Showing English Content\n\n**Check symlinks:**\n```bash\nls -la docs/nl/assets\n# Should show: assets -\u003e ../en/assets\n```\n\n## 📞 Support\n\n### Documentation Issues\n\n- **Issue tracker**: [GitLab Issues](https://git.open-regels.nl/showcases/iou-architectuur/-/issues)\n- **Email**: mailto:steven.gort@ictu.nl\n\n### Technical Support\n\n- **MkDocs**: [https://www.mkdocs.org/](https://www.mkdocs.org/)\n- **Material Theme**: [https://squidfunk.github.io/mkdocs-material/](https://squidfunk.github.io/mkdocs-material/)\n- **Azure Static Web Apps**: [https://docs.microsoft.com/azure/static-web-apps/](https://docs.microsoft.com/azure/static-web-apps/)\n\n## 📚 Additional Resources\n\n- [MkDocs Documentation](https://www.mkdocs.org/)\n- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)\n- [Markdown Guide](https://www.markdownguide.org/)\n- [Azure Static Web Apps Documentation](https://docs.microsoft.com/azure/static-web-apps/)\n\n## 📄 License\n\nThis documentation is licensed under the **European Union Public License v1.2** (EUPL-1.2).\n\n## 🎯 Project Information\n\n- **Organization**: Provincie Flevoland \u0026 RONL Initiative\n- **Project**: IOU Architecture Framework\n- **Status**: ✅ Production\n- **Version**: 0.4\n- **Last Updated**: February 2026\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgort%2Fiou-architectuur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgort%2Fiou-architectuur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgort%2Fiou-architectuur/lists"}