maj/nextcloud-share
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
631046df34ed293fdbac5d32e7a242af702a2df7
nextcloud-share/.plans/CreateProject.md
Tom Hicks ff3c83ab1f Creates initial project.
2026-01-26 22:21:12 -08:00

12 KiB
Raw Blame History

Project Creation Plan: Nextcloud Share for Game Consoles

Created: 2026-01-26
Status: In Progress
Target Platform (Initial): Nintendo 3DS

Project Overview

Create a cross-platform homebrew application for game consoles that allows users to upload screenshots, recordings, and other files from their devices to Nextcloud servers. The initial target platform is Nintendo 3DS, with planned support for WiiU, Switch, PS Vita, and potentially Android/iOS/PC.

Core Requirements

  • C/C++ codebase with shared library for common functionality
  • Support for multiple Nextcloud instances via user-provided URLs
  • Local filesystem browsing and file selection
  • Favorite and recent folder management
  • Docker/Podman-based build system (no local toolchain installation required)
  • Git-flow workflow with feature branches
  • Gitea issue tracking integration

Project Structure

nextcloud-share/
├── .plans/                    # Feature plans and documentation
├── .github/                   # CI/CD workflows (if using GitHub mirror)
├── .gitea/                    # Gitea-specific CI workflows
├── shared/                    # Shared C/C++ library (libnextcloud)
│   ├── include/              # Public headers
│   ├── src/                  # Implementation
│   ├── tests/                # Unit tests
│   └── CMakeLists.txt        # Build configuration
├── 3ds/                      # Nintendo 3DS homebrew app
│   ├── src/                  # 3DS-specific code
│   ├── resources/            # Icons, banners, etc.
│   ├── Makefile              # devkitARM build
│   └── README.md             # 3DS build instructions
├── docker/                   # Dockerfile definitions
│   ├── devkitarm.Dockerfile  # 3DS build environment
│   └── README.md             # Container usage guide
├── scripts/                  # Build and utility scripts
├── config.example            # Example configuration file
├── .gitignore
├── README.md
└── LICENSE

Phase 1: Project Initialization

1.1 Repository Setup

  • Clone template repository
  • Create repository on git.tomusan.com
  • Configure git-flow (main/develop branches)
  • Add initial .gitignore entries
  • Update README.md with project information

1.2 Configuration Management

  • Create config.example.json file with template for:
    • Nextcloud URL(s)
    • Test username(s)
    • Test password(s)
    • Build-time options (maxRecentFolders, etc.)
  • Document environment variable overrides for CI:
    • NEXTCLOUD_TEST_URL
    • NEXTCLOUD_TEST_USER
    • NEXTCLOUD_TEST_PASSWORD
    • Environment variables take precedence over JSON config
  • Add config.json and config to .gitignore
  • Add documentation about local config setup
  • Integrate nlohmann/json (header-only, no build dependency)

1.3 Docker/Podman Build Environment

  • Create Dockerfile for devkitARM (3DS development)
  • Create build scripts for containerized compilation
  • Document podman commands for:
    • Building container images
    • Running builds
    • Running tests
    • Interactive development shell
  • Test container build process

Phase 2: Shared Library (libnextcloud)

2.1 Library Architecture

  • Define public API interface (C++17)
  • Set up CMake build system for shared library
  • Integrate nlohmann/json (header-only)
  • Integrate Google Test for unit testing
  • Implement WebDAV client for Nextcloud
    • HTTP/HTTPS client wrapper (libcurl)
    • WebDAV protocol implementation (PROPFIND, PUT, MKCOL)
    • XML response parsing (tinyxml2)
  • Authentication handling (HTTP Basic Auth initially)
  • File upload functionality with chunking support
  • Folder listing/browsing via WebDAV PROPFIND
  • Configuration management (JSON parsing and validation)

2.2 Core Features

  • Connection manager
    • URL validation
    • Server connectivity testing
    • Authentication verification
  • Upload manager
    • File streaming
    • Progress tracking
    • Error handling and retry logic
  • Folder management
    • List remote folders
    • Create folders
    • Save favorite folders
    • Track recent folders (configurable limit)

2.3 Testing

  • Unit tests for WebDAV client
  • Integration tests with test Nextcloud instances
  • Mock server for offline testing

Phase 3: Nintendo 3DS Implementation

3.1 3DS-Specific Development

  • Set up devkitARM build configuration
  • Implement 3DS UI using citro3d/citro2d
  • SD card filesystem access
  • Screenshot/recording detection
  • Integration with shared library
  • CIA and 3DSX packaging

3.2 Features

  • Main menu UI
  • Nextcloud server configuration screen
  • File browser (SD card)
  • Upload progress display
  • Settings/preferences screen
  • Favorite folders management
  • Recent folders display

Phase 4: CI/CD and Automation

4.1 Gitea Integration

  • Configure Gitea Actions or webhooks
  • Automated builds on push/PR
  • Run tests in containers
  • Generate build artifacts
  • Update build status badges

4.2 Quality Checks

  • Linting (clang-tidy or similar)
  • Code formatting checks (clang-format)
  • Static analysis
  • Test coverage reporting

Phase 5: Documentation

5.1 User Documentation

  • Installation guide (per platform)
  • Configuration guide
  • Usage instructions
  • FAQ
  • Troubleshooting guide

5.2 Developer Documentation

  • Architecture overview
  • API documentation (Doxygen?)
  • Build instructions (local and container)
  • Contributing guidelines
  • Code style guide

Dependencies

Build Dependencies (in containers)

  • Nintendo 3DS:
    • devkitARM
    • libctru
    • citro3d / citro2d (for UI)
    • makerom (for CIA generation)
    • tex3ds (for texture conversion)

Library Dependencieswith SSL/TLS support (mbedTLS for embedded platforms)

  • XML Parsing: tinyxml2 (lightweight, for WebDAV PROPFIND responses)
  • JSON: nlohmann/json v3.11+ (header-only, for config files)
  • Testing: Google Test (gtest) v1.14+
  • Build System: CMake 3.15+

C++ Requirements

  • Standard: C++17
  • Compiler Support:
    • GCC 7+ (devkitARM)
    • Clang 5+
    • MSVC 2017+ (for Windows builds)
    • Android NDK r19+g files)
  • Testing: Catch2 or Google Test (optional)

Runtime Dependencies

  • User's Nextcloud server (version 20+ recommended)
  • Network connectivity on device
  • SD card (for 3DS) with sufficient space

Gitea Issues to Create

The following issues should be created on git.tomusan.com for tracking:

Epic/Milestone Issues

  1. #1: Project Infrastructure Setup

    • Description: Set up repository, CI/CD, Docker containers, and documentation
    • Labels: infrastructure, epic

  2. #2: Shared Library Development (libnextcloud)

    • Description: Develop shared C/C++ library for Nextcloud connectivity
    • Labels: library, core, epic

  3. #3: Nintendo 3DS Homebrew App

    • Description: Develop 3DS-specific homebrew application
    • Labels: platform:3ds, epic

Infrastructure Issues (Milestone #1)

  1. #4: Configure git-flow workflow

    • Description: Initialize git-flow with main/develop branches
    • Labels: infrastructure, setup

  2. #5: Create Docker build environment for devkitARM

    • Description: Dockerfile and scripts for 3DS compilation
    • Labels: infrastructure, docker, 3ds

  3. #6: Set up configuration file system

    • Description: Create config.example and document environment variable overrides
    • Labels: infrastructure, configuration

  4. #7: Implement Gitea CI/CD pipeline

    • Description: Automated builds, tests, and status badges
    • Labels: infrastructure, ci-cd, gitea

Shared Library Issues (Milestone #2)

  1. #8: Design and implement WebDAV client

    • Description: HTTP client for Nextcloud's WebDAV API
    • Labels: library, core, networking

  2. #9: Implement authentication system

    • Description: Handle Basic Auth and session management
    • Labels: library, core, security

  3. #10: Implement file upload functionality

    • Description: Streaming uploads with progress tracking
    • Labels: library, core, feature

  4. #11: Implement folder management

    • Description: List, create, and navigate remote folders
    • Labels: library, core, feature

  5. #12: Implement favorites and recent folders

    • Description: Persistence layer for user preferences
    • Labels: library, feature

  6. #13: Write unit tests for shared library

    • Description: Test coverage for core functionality
    • Labels: library, testing

3DS Platform Issues (Milestone #3)

  1. #14: Initialize 3DS project structure

    • Description: Set up devkitARM build files and basic app skeleton
    • Labels: platform:3ds, setup

  2. #15: Implement 3DS UI framework

    • Description: Menu system and screens using citro2d
    • Labels: platform:3ds, ui

  3. #16: Implement SD card file browser

    • Description: Browse and select files from SD card
    • Labels: platform:3ds, feature

  4. #17: Integrate shared library with 3DS app

    • Description: Link libnextcloud and implement network stack
    • Labels: platform:3ds, integration

  5. #18: Implement 3DS settings screen

    • Description: Server configuration and preferences UI
    • Labels: platform:3ds, ui, feature

  6. #19: Create CIA and 3DSX distribution packages

    • Description: Packaging scripts and testing
    • Labels: platform:3ds, distribution

Documentation Issues

  1. #20: Write user documentation

    • Description: Installation, configuration, and usage guides
    • Labels: documentation, user-facing

  2. #21: Write developer documentation

    • Description: Architecture, API docs, contributing guide
    • Labels: documentation, developer

.gitignore Updates

Add the following entries:

# Local configuration (contains secrets)
config
*.config
!config.example
!*.config.example

# Build artifacts
build/
*.o
*.a
*.so
*.elf
*.3dsx
*.smdh
*.cia
*.3ds

# IDE and editor files
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

# Container volumes
.docker-volumes/

# Test outputs
test-results/
coverage/

# Platform-specific
3ds/build/
wiiu/build/
switch/build/
vita/build/

README.md Updates

Key sections to add:

  1. Project description and goals
  2. Supported platforms (current and planned)
  3. Features list
  4. Prerequisites (Podman/Docker)
  5. Quick start guide
  6. Building instructions (using containers)
  7. Configuration setup
  8. Contributing guidelines
  9. License information
  10. Build status badges (once CI is set up)

Next Steps

  1. Discuss and refine issue content - Review each planned issue and adjust descriptions, acceptance criteria, and priorities
  2. Create plan for issue creation - .plans/CreateGiteaIssues.md
  3. Create issues on Gitea - Bulk create or create incrementally
  4. Set up git-flow - Initialize develop branch
  5. Implement issues sequentially - Starting with infrastructure (#4-#7)

Technical Decisions

Resolved

  • C++ Standard: C++17 (best balance of modern features and cross-platform support)
  • Build System: CMake (industry standard, excellent cross-platform support)
  • Testing Framework: Google Test (gtest/gmock)
  • Project License: MIT License
  • Config Format: JSON using nlohmann/json (header-only library)
  • Nextcloud API: WebDAV (same protocol as desktop sync client)

To Be Resolved

  • Should we support OAuth2 flow or just Basic Auth initially? (Start with Basic Auth)
  • Preferred UI library for 3DS (citro2d, custom, or existing framework)?
  • SSL/TLS library: mbedTLS, OpenSSL, or platform-specific?
  • HTTP library: libcurl (if available) or custom implementation?

Notes

  • Test URLs: https://cloud.tomusan.com and https://disobedient.cloud/nextcloud
  • These should only be in local config files, never committed
  • CI should support environment variable injection for test credentials
  • Build container should be versioned and tagged for reproducibility
  • Consider multi-stage Docker builds to minimize image size
Reference in New Issue View Git Blame Copy Permalink