web-hosts/domains/coppertone.tech/GEMINI.md

GEMINI.md - Project Context for Copper Tone Technologies

This document provides a comprehensive overview of the coppertone.tech project, intended to serve as instructional context for Gemini Agent interactions.

Project Overview

The "Hopoyuksa Tali Lakna" (Copper Tone Technologies) project aims to establish a robust digital presence for an autochthonous American Indian company specializing in IT field services, emerging technology, and cryptocurrency. The core deliverables include a public-facing promotional website, an internal work scheduling and management system, and a client portal with multi-modal payment capabilities (CC, Crypto).

The entire solution is designed for complete self-sovereignty and enterprise-grade infrastructure, leveraging containerization with Podman and a suite of self-hosted services.

Key Features:

• Company Promotion: Showcase services, expertise, and tribal identity.
• Work Management: Internal system for scheduling, assigning, and tracking in-house and contract work.
• Client Portal: Secure access for clients to view project progress, communications, and manage invoices.
• Payment Gateway: Accept payments via credit card (Stripe) and cryptocurrencies (BTCPay Server).
• Real-time Communication: Integrated messaging capabilities within the platform.
• Decentralized Storage: Exploration of IPFS (via Helia and IPFS-interchangeable backend) for resilient data storage and content delivery.

Planned Technology Stack:

• Frontend: Vue 3 (as a Progressive Web App - PWA), Tailwind CSS, Vue Router
• State Management: Pinia
• Content Management: Markdown (for dynamic content like services and blog posts)
• Decentralization (Frontend): Helia (IPFS implementation for JavaScript)
• Backend: Go 1.25+ (designed for serverless deployment and IPFS interchangeability), PostgreSQL (database), Blockchain integration (for specific features like identity, smart contracts, or verifiable transactions).
• Containerization: Podman
• Version Control: Self-hosted Gitea
• CI/CD: Self-hosted Gitea Actions
• Messaging: Matrix (Synapse homeserver)
• Email: Self-hosted email server (e.g., Mailu)

Building and Running the Project

As of this GEMINI.md creation, the project is in its initial planning and setup phase. Actual code for the frontend and backend has not yet been written. Therefore, specific build and run commands are currently placeholders. The emphasis is on running all development, testing, and production environments via Podman/Podman Compose.

Refer to docs/project-plan/phases/Phase-1-Foundation-and-Infrastructure.md for detailed instructions on the initial setup of the development environment, including project scaffolding and containerization.

General Flow (as planned):

• Containerized Environment: The entire application will run within Podman containers, orchestrated by podman-compose.yml.
• Frontend Build: The Vue.js PWA application will be built using npm run build within its container.
• Backend Deployment: Go serverless functions will be deployed and managed within a Podman-orchestrated environment.
• Database: PostgreSQL will run as a dedicated container.
• Gitea/Gitea Actions: These services will also run as containers, providing Git hosting and CI/CD.

Development Conventions

Strict adherence to a well-defined development process is paramount for this enterprise-grade project.

• Enterprise Git Workflow:

  • Branching Model: Inspired by GitFlow, utilizing main (production-ready), testing (pre-production QA), develop (integration), feature/*, bugfix/*, and hotfix/* branches.
  • Pull Requests (PRs): All code changes, modifications, or deletions MUST occur within a dedicated feature or bugfix branch, pushed to the self-hosted Gitea, and merged into develop via a Pull Request.
  • CI/CD Integration: PRs will automatically trigger Gitea Actions CI to run tests. Merging into develop will trigger a PR to testing, which deploys to a staging environment. Merging testing into main will trigger a production deployment.
  • For full details, refer to docs/project-plan/Git-Workflow.md.

• Code Quality & Testing:

  • Linting & Formatting: ESLint and Prettier will be configured for consistent code style across the frontend (Vue.js/TypeScript). Go linting tools will be configured for the backend.
  • Unit Testing: Vitest will be used for unit tests in the frontend. Go's built-in testing framework will be used for backend unit tests.
  • End-to-End (E2E) Testing: Cypress will be employed for E2E tests to validate complete user flows.
  • Tests will be an integral part of the CI/CD pipeline, ensuring only tested code is merged.

• Documentation:

  • Comprehensive project planning documents are located in the docs/project-plan/ directory, including detailed breakdowns for each phase.

---

Current Status (as of 2025-11-20):

• Project initialization complete.
• Git repository initialized with main, develop, and testing branches.
• Initial project plans and Git workflow documentation committed and updated for Gitea Actions.
• Next step: Update README.md and detailed project phase plans to reflect the new architectural decisions.