TSYSDevStack-SupportStack-Cloudron/AGENTS.md

TSYS Cloudron Packaging Project - AI Agent Context

This file contains important context, guidelines, and decisions made during the development of the TSYS Cloudron Packaging Project. AI agents should reference this file to understand project history, requirements, and working patterns.

Project Overview

Mission Statement

Package 58+ upstream free/libre/open applications for deployment onto Cloudron (TSYS Group's PaaS of choice) as part of the TSYS Group Development Stack.

Key Stakeholders

• Project Lead: Charles N Wyble (@REachableCEO) - The founder
• Timeline: 48-hour delivery deadline for Cloudron, Lifecycle, and Toolbox components
• Target Completion: 2025-11-15
• QA/Testing Period: 2025-11-10 to 2025-11-15

Project Structure

TSYSDevStack/
└── Platform/
    └── Cloudron/
        ├── README.md                    # Comprehensive project documentation
        ├── GitUrlList.txt              # Master list of upstream repositories
        ├── clone-repos.sh              # Automated repository cloning script
        ├── AGENTS.md                   # This file - AI agent context
        ├── .gitignore                  # Git ignore rules
        ├── Package-Artifacts/          # Completed Cloudron packages
        └── Package-Workspace/         # Working directory organized by function
            ├── API-Gateway/           # 2 apps
            ├── Automation/            # 4 apps
            ├── Business-Apps/         # 9 apps
            ├── Collaboration/         # 2 apps
            ├── Communication/         # 2 apps
            ├── Data-Management/       # 2 apps
            ├── Development/           # 4 apps
            ├── DevOps-Tools/         # 2 apps
            ├── Documentation-Tools/   # 3 apps
            ├── Financial-Payments/    # 1 app
            ├── Financial-Trading/     # 1 app
            ├── Infrastructure/        # 6 apps
            ├── Legal/                # 1 app
            ├── Low-Code/             # 3 apps
            ├── Monitoring/           # 6 apps
            ├── Project-Management/    # 1 app
            ├── Scientific-Computing/  # 2 apps
            ├── Security/             # 5 apps
            └── System-Administration/ # 3 apps

Key Decisions & Rationale

1. Organization Strategy

Decision: Organize applications by function rather than programming language.

Rationale:

• Founder explicitly requested functional organization over language-based organization
• More intuitive for developers working on Cloudron packaging
• Aligns with how users will discover and deploy applications
• Facilitates better documentation and user experience

Implementation: 20 functional categories created based on application purpose and use cases.

2. Repository Management

Decision: Clone all upstream repositories into Package-Workspace but exclude from git.

Rationale:

• Avoid polluting the project repository with large upstream codebases
• Enable offline development and packaging work
• Maintain clean separation between packaging code and upstream source
• Provide reproducible development environment

Implementation:

• .gitignore excludes Package-Workspace/**/repo/
• clone-repos.sh script enables other developers to replicate workspace
• Each app has its own directory with repo/ subdirectory

3. Documentation Strategy

Decision: Create comprehensive README.md with application inventory table.

Rationale:

• Single source of truth for project status and application catalog
• Beautiful, clickable table with links to vendor websites and repositories
• Scalable approach for adding new applications
• Professional presentation for stakeholders

Implementation:

• Markdown table with Application Name (linked to vendor site), Repository (linked to git), Description, and Functional Category
• Project statistics and overview sections
• Development workflow documentation

4. Automation Approach

Decision: Create automated cloning script with error handling and categorization.

Rationale:

• Enable other developers to quickly set up development environment
• Reduce manual setup time and potential errors
• Provide consistent workspace structure
• Handle edge cases and provide helpful error messages

Implementation:

• clone-repos.sh with colored output, timeout handling, and automatic categorization
• Functional category mapping based on application names
• Progress reporting and summary statistics

Technical Requirements

Cloudron Packaging Standards

• Each application requires Dockerfile and CloudronManifest.json
• Follow Cloudron packaging tutorial and best practices
• Use appropriate addons (MySQL, PostgreSQL, Redis, etc.)
• Ensure proper security and configuration management
• Test with cloudron build and cloudron install

Quality Assurance

• All work must be QA'd early and often
• Use Docker security scanning tools (hadolint, trivy, dockle, dive, syft)
• Perform at least 5 validation checks per component
• Treat warnings as errors and resolve all issues
• No unit/end-to-end test suite means work is not complete

Git Standards

• Use atomic commits with conventional commit standards
• Make verbose and beautiful commit messages
• Commit early and often
• Use gh/tea commands for pull requests and releases
• Commit history should serve as a comprehensive project journal

Container Standards

• Use Docker containers for all work (no host pollution)
• Only use docker and git commands on host
• Use curl for health checks
• Do not install tooling/packages/runtimes on host

Working Patterns

Multi-Component Development

• Chats start at project root or component root level
• Only orient from invoked location down
• Do not consider sibling directories
• Confine work to directory (and below) where invoked

Communication Style

• Brief, professional, direct communication
• Avoid unnecessary fluff or excessive politeness
• Focus on task completion and technical accuracy
• Keep responses concise (fewer than 4 lines unless detail requested)

Documentation Maintenance

• Update both AI-readable (AGENTS.md) and human-readable (JOURNAL.md) journals during each interaction
• Maintain running log of work done, remaining tasks, and important notes
• Keep documentation in sync with code artifacts

Application Categories & Mappings

Functional Categories (19 total)

1. API-Gateway (2 apps): apisix, webhook
2. Automation (4 apps): runme, rundeck, huginn, windmill
3. Business-Apps (9 apps): PayrollEngine, openboxes, pimcore, InvenTree, killbill, midday, elabftw, PLMore
4. Collaboration (2 apps): grist-core, consuldemocracy
5. Communication (2 apps): craig, fonoster
6. Data-Management (2 apps): datahub, seatunnel
7. Development (4 apps): AutoBOM, reviewboard, puter, warp
8. DevOps-Tools (2 apps): fx, policies
9. Documentation-Tools (3 apps): docker-drawio, wireviz-web, WireViz
10. Financial-Payments (1 app): hyperswitch
11. Financial-Trading (1 app): nautilus_trader
12. Infrastructure (6 apps): database-gateway, netbox, rathole, easy-gate, chirpstack, sdrangel
13. Legal (1 app): docassemble
14. Low-Code (3 apps): openblocks, corteza, no-code-architects-toolkit
15. Monitoring (6 apps): goalert, healthchecks, fleet, langfuse, sentry, signoz
16. Project-Management (1 app): Core
17. Scientific-Computing (2 apps): boinc, jamovi
18. Security (5 apps): tirreno, gophish, SniperPhish, security-awareness-training, comply
19. System-Administration (3 apps): mender, mendersoftware, slurm

Programming Languages Identified

• Go (14 apps)
• Node.js/JavaScript (13 apps)
• Python (20 apps)
• PHP (3 apps)
• Java (2 apps)
• Rust (1 app)
• Ruby (1 app)
• TypeScript (1 app)
• Mixed/Unknown (3 apps)

Important Notes

Repository Issues

• oat-sa: Invalid URL (organization-level only)
• satnogs: GitLab repository requiring authentication
• mendersoftware: Fixed with correct URL to mender repository

Duplicate Entries

• warp and windmill appeared twice in original GitUrlList.txt

Recent Additions

• Craig (craig): Added during session, TypeScript Discord voice recording bot, placed in Communication category

Functional Categorization Audit (2025-11-13)

Decision: Conducted comprehensive audit of application categorization to ensure proper functional grouping.

Critical Fixes Implemented:

• fonoster: Moved from Development to Communication (telephony platform)
• hyperswitch: Moved from Business-Apps to Financial-Payments (payments infrastructure)
• nautilus_trader: Moved from Business-Apps to Financial-Trading (algorithmic trading)
• docassemble: Moved from Legal/repo to Legal directory (document assembly platform)
• no-code-architects-toolkit: Moved from Development to Low-Code (low-code platform)
• docker-drawio: Moved from Development to Documentation-Tools (diagramming tool)
• wireviz-web: Moved from Voice-Audio to Documentation-Tools (cable diagramming)
• WireViz: Moved from Voice-Audio to Documentation-Tools (cable documentation)
• corteza: Moved from DevOps-Tools to Low-Code (low-code platform)
• comply: Moved from DevOps-Tools to Security (compliance and security)
• policies: Moved from Development to DevOps-Tools (DevOps policies)

New Categories Created:

• Documentation-Tools: For diagramming and documentation applications
• Financial-Payments: For payment processing and financial infrastructure
• Financial-Trading: For trading and financial algorithm platforms

Categories Removed:

• Voice-Audio: Removed as empty (WireViz moved to Documentation-Tools)

Rationale:

• Improved accuracy in functional categorization
• Better user experience for application discovery
• More logical grouping for Cloudron packaging workflows
• Reduced category ambiguity and overlap

Development Workflow

For New Applications

1. Add to GitUrlList.txt
2. Run ./clone-repos.sh to fetch repository
3. Determine appropriate functional category
4. Move to correct directory if needed
5. Update README.md table
6. Begin Cloudron packaging (Dockerfile + CloudronManifest.json)
7. Test with Cloudron CLI
8. Move completed package to Package-Artifacts/

For AI Agents

1. Always read AGENTS.md first for context
2. When resuming work: Check RESUME.md for session status and next steps
3. Update AGENTS.md with important decisions and changes
4. Maintain professional, concise communication style
5. Focus on task completion and technical accuracy
6. Use todo system for tracking complex tasks
7. Perform thorough QA before marking tasks complete

Project Status

Completed Tasks

• ✅ Repository analysis and language identification
• ✅ Functional directory structure creation
• ✅ Application organization by function
• ✅ Git ignore configuration
• ✅ Comprehensive README.md documentation
• ✅ Automated cloning script
• ✅ AI agent context documentation
• ✅ Functional categorization audit and corrections

Next Steps

• Begin Cloudron packaging for high-priority applications
• Establish testing and validation pipeline
• Create package templates for common patterns
• Develop automated packaging workflows

Session Resume Guide

📍 Resuming Work? Read RESUME.md first!

When returning to this project after a break:

1. Always check RESUME.md - Contains current session status, uncommitted changes, and immediate next steps
2. Review this file (AGENTS.md) for context, decisions, and working patterns
3. Review README.md for complete project documentation
4. Check git status to see what's uncommitted

RESUME.md provides:

• Summary of work done in previous session
• List of uncommitted changes
• Immediate next steps with commands
• Known issues and resolutions
• Quick start guides for different scenarios

---

Last Updated: 2025-11-13
Session Context: Functional categorization audit and corrections
AI Agent: Qwen
Project Phase: Foundation complete, categorization optimized, ready for packaging phase