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

QWEN.md - Copper Tone Technologies Project Context

Project Overview

Copper Tone Technologies (aka "Hopoyuksa Tali Lakna") is a comprehensive digital platform built for an autochthonous American Indian company specializing in IT field services, emerging technology, and cryptocurrency. The project aims to provide:

• Public-facing promotional website to showcase company services, tribal identity, and expertise
• Internal work management system for scheduling, tracking, and managing in-house and contract work
• Client portal with multi-modal payment capabilities (credit cards, cryptocurrency)
• Real-time communication integrated messaging capabilities
• Decentralized data storage using IPFS for resilient and verifiable data

The project is production-ready with 95%+ completion and all core features implemented.

Architecture & Technology Stack

Frontend

• Framework: Vue 3 (Progressive Web App - PWA)
• Routing: Vue Router
• Styling: Tailwind CSS
• State Management: Pinia
• Content Management: Markdown with gray-matter
• Decentralization: Helia (IPFS implementation for JavaScript)
• Build Tool: Vite
• Type Safety: TypeScript

Backend

• Language: Go 1.25+ (designed for serverless deployment)
• Architecture: Microservices with individual services for auth, work management, and payments
• Database: PostgreSQL
• Blockchain Integration: Ethereum integration for identity and verifiable transactions
• Containerization: Each service runs in its own Podman container

Infrastructure

• Containerization: Podman with Podman Compose
• Version Control: Self-hosted Gitea
• CI/CD: Gitea Actions
• Messaging: Matrix (Synapse homeserver)
• Email: Self-hosted email server
• Decentralized Storage: IPFS via Kubo
• Payment Processing: Stripe integration and cryptocurrency support

Key Services

Backend Services (Go-based microservices)

1. Auth Service - Multi-factor authentication (email/password + blockchain), JWT management, role-based access
2. Work Management Service - Project, task, and work order management with IPFS integration
3. Payment Service - Multi-modal payment processing (CC, Crypto) with Stripe integration
4. IPFS Service - Decentralized data storage and retrieval

Container Orchestration

The platform uses a comprehensive podman-compose.yml to orchestrate:

• Frontend (Vue.js PWA)
• Multiple backend microservices
• PostgreSQL database with initialization
• IPFS node
• Reverse proxy capabilities

Development Environment Setup

Prerequisites

• Podman 4.0+ (or Docker 24.0+)
• Podman Compose 1.0+ (or Docker Compose 2.20+)
• Git 2.30+
• Go 1.25+ (for backend development)
• Node.js 20.x LTS (for frontend development)

Initial Setup

# Clone the repository
git clone ssh://git@git.coppertone.tech:2222/administrator/CopperTone.Tech.git
cd CopperTone.Tech

# Build and start services
podman-compose build
podman-compose up -d

Development Conventions

Git Workflow (CRITICAL - MUST FOLLOW)

The project follows a strict enterprise GitFlow model with mandatory PR reviews and automated CI checks:

• main: Production-ready code. Direct pushes STRICTLY FORBIDDEN.
• testing: Pre-production QA/staging environment. Direct pushes FORBIDDEN. Code enters via PR from develop.
• develop: Primary integration branch. Direct pushes FORBIDDEN. Code enters via PR from feature/bugfix branches.
• feature/<name>: New features (branch from develop)
• bugfix/<name>: Bug fixes (branch from develop)
• hotfix/<name>: Critical production fixes (branch from main, merge to BOTH main AND develop)

Mandatory Workflow Process:

1. Create branch from develop
2. Commit changes with clear, logical commit messages
3. Push branch: git push -u origin feature/my-feature
4. Open Pull Request to develop in Gitea UI
5. Automated CI checks trigger (linting, type checking, unit tests, E2E tests)
6. Code review (optional but recommended)
7. Merge after approval and ALL CI checks pass (use "Squash and Merge")

Code Quality & Testing

• Frontend: ESLint, Prettier, Vitest for unit tests, Cypress for E2E tests
• Backend: Go's built-in testing framework for unit tests
• CI/CD: All changes must pass automated tests before merging

Security Considerations

• JWT authentication across all API endpoints
• Password hashing with bcrypt
• Ethereum signature verification
• Role-based access control (RBAC)
• SQL injection protection
• CORS properly configured
• Environment variable management

Project Structure

coppertone.tech/
├── backend/                    # Go microservices
│   ├── functions/              # Individual services (auth, work, payment)
│   │   ├── auth-service/       # JWT auth, user registration/login with blockchain support
│   │   ├── work-management-service/ # Projects, tasks, work orders
│   │   └── payment-service/    # Invoice and payment processing
│   ├── migrations/             # Database migration scripts
│   ├── pkg/                    # Shared Go packages
│   ├── scripts/                # Build and deployment scripts
│   └── Containerfile.db-init   # Database initialization container
├── docs/                       # Documentation
│   ├── audits/                 # Security and code audits
│   └── project-plan/           # Project planning documents
├── frontend/                   # Vue 3 PWA frontend
│   ├── public/                 # Static assets
│   ├── src/                    # Source code
│   │   ├── components/         # Vue components (ui/, layout/, views/)
│   │   ├── stores/             # Pinia state management
│   │   ├── views/              # Page-level components
│   │   └── router/             # Vue Router configuration
│   ├── cypress/                # E2E tests
│   └── package.json            # Frontend dependencies and scripts
├── .claude/                    # Claude-specific settings
├── .gitea/                     # Gitea configuration
├── .gopath/                    # Go workspace (if needed)
├── podman-compose.yml          # Container orchestration
├── README.md                   # Main project overview
├── CLAUDE.md                   # Comprehensive development guide for Claude
├── DEPLOYMENT.md               # Production deployment guide
├── GEMINI.md                   # Technical context for AI agents
├── PROGRESS.md                 # Detailed progress tracking
├── PRODUCTION_CHECKLIST.md     # Pre-deployment validation
└── other documentation files

Building and Running

Development

# Start all services in development mode
podman-compose up

# Frontend development server
cd frontend && npm run dev

# Backend services are built automatically via the Containerfile

Production

# Build all containers
podman-compose build

# Start services in detached mode
podman-compose up -d

# Access services:
# Frontend: http://localhost:8080
# Auth Service: http://localhost:8082
# Work Management: http://localhost:8083
# Payment Service: http://localhost:8084
# IPFS Gateway: http://localhost:8085

Environment Configuration

Create a .env file with the following variables:

# Database Configuration
DB_USER=coppertone_user
DB_PASSWORD=your_secure_password
DB_NAME=coppertone_db
DB_HOST=db

# JWT Authentication
JWT_SECRET=your_long_random_string_at_least_32_chars

# Stripe Payment Integration
STRIPE_SECRET_KEY=sk_live_your_stripe_secret_key
STRIPE_PUBLIC_KEY=pk_live_your_stripe_public_key

# Frontend Configuration
VITE_AUTH_API_URL=https://auth.coppertone.tech
VITE_WORK_API_URL=https://work.coppertone.tech
VITE_PAYMENT_API_URL=https://payment.coppertone.tech

Key Files and Directories

• podman-compose.yml: Container orchestration configuration
• README.md: Main project overview
• CLAUDE.md: Comprehensive development guide with architecture details
• GEMINI.md: Technical project details for AI agents
• DEPLOYMENT.md: Production deployment guide
• PROGRESS.md: Detailed progress tracking and status
• PRODUCTION_CHECKLIST.md: Pre-deployment validation checklist
• docs/project-plan/: Detailed project planning documentation
• docs/project-plan/Git-Workflow.md: Git workflow specifications
• docs/project-plan/Team-Collaboration-and-Tracking.md: Collaboration guidelines
• frontend/package.json: Frontend dependencies and scripts
• backend/functions/: Backend microservices
• backend/migrations/: Database migration scripts

Development Phases & Project Plan

Phase 1: Foundation & Infrastructure (Sprints 1-2) ✅ COMPLETED

• Git repository initialization
• Podman containerization
• Vue 3 + Tailwind + Pinia setup
• Gitea and Gitea Actions CI/CD

Phase 2: Core Frontend Development (Sprints 3-5) ✅ MOSTLY COMPLETE

• Public-facing pages (Home, About, Contact, Services, Blog)
• PWA implementation
• Markdown content rendering (services, blog articles)
• Component library (layout, UI components)

Phase 3: Backend Development & Blockchain (Sprints 6-9) ✅ 95% COMPLETE

• Go serverless functions setup
• Multi-factor authentication (email/password + blockchain identity)
• Work management API with IPFS integration
• Payment gateway (Stripe, BTCPay Server, direct blockchain transactions)

Phase 4: Client Portal & Work Management UI (Sprints 10-12) ⏳ 0% Complete

• Client dashboard (view projects, invoices, payment history)
• Internal work management dashboard
• Frontend-backend integration (Pinia state management)

Phase 5: Advanced Features (Sprints 13-15) ⏳ 0% Complete

• Helia/IPFS frontend integration
• Matrix messaging integration
• Self-hosted email server (Mailu)
• Advanced blockchain features (smart contracts, decentralized storage proofs)

Phase 6: Testing, Deployment & Launch (Sprint 16) ⏳ 15% Complete

• End-to-end testing (Cypress)
• Finalize CI/CD pipeline
• Production deployment
• Monitoring, logging, backup plan

Backend Service Architecture

Auth Service (port 8082)

Purpose: Multi-factor authentication supporting email/password AND blockchain identity.

Implemented endpoints:

• POST /register-email-password: Register with email/password
• POST /register-blockchain: Register with blockchain address/DID (signature verification)
• POST /login-email-password: Login with email/password (returns JWT)
• POST /login-blockchain: Login with blockchain signature (returns JWT)
• POST /link-identity: Link additional identity to existing account
• POST /unlink-identity: Unlink an identity
• GET /profile: Protected route (JWT required)

Features:

• Email/password auth with JWT and bcrypt password hashing
• Blockchain signature verification
• Identity linking system
• Role-based access control (RBAC)

Work Management Service (port 8083)

Purpose: CRUD operations for projects, tasks, work orders with IPFS integration.

Implemented endpoints:

• /projects: GET (list), POST (create), PUT, DELETE
• /projects/:id: GET, PUT, DELETE
• /projects/:id/tasks: GET, POST
• /tasks/:id: GET, PUT, DELETE
• /workorders: CRUD operations

IPFS Integration: Store project documents on IPFS, save CIDs in PostgreSQL for retrieval.

Payment Service (port 8084)

Purpose: Invoice and payment processing with multi-modal payment support.

Implemented endpoints:

• /invoices: CRUD operations
• /payments: CRUD operations
• Stripe Payment Intent creation

Frontend Architecture

Routing

Vue Router with lazy-loaded routes:

• / - Home
• /about - About
• /services - Services list
• /services/:slug - Service detail (dynamic)
• /blog - Blog list
• /blog/:slug - Article detail (dynamic)
• /contact - Contact
• /login, /register - Authentication
• /dashboard - User dashboard

Component Structure

• Layout components (components/layout/): TheHeader.vue, TheFooter.vue, Navbar.vue
• UI components (components/ui/): BaseCard.vue, FormInput.vue, CtaButton.vue, Spinner.vue
• View-specific components (components/views/<ViewName>/): Organized by parent view

State Management

Pinia stores in src/stores/:

• Auth Store: Authentication state, registration/login, identity linking
• Projects Store: Project CRUD operations, state management
• Tasks Store: Task CRUD operations, filtering
• Invoices Store: Invoice and payment management

Database

PostgreSQL 16 running in container. Schema managed with automated migrations.

Database Features:

• Users table with multi-factor authentication support
• Identities table for linking multiple authentication methods
• Roles table for RBAC system
• Projects, tasks, and work orders with IPFS integration
• Invoices and payments with blockchain transaction tracking
• Automated status updates via database triggers

CI/CD

Gitea Actions configured in .gitea/workflows/. Current workflows include:

• Backend services testing and building
• Frontend building and quality checks
• Automated testing on every commit
• Code coverage reporting
• Dependency caching for faster builds

Team Collaboration & Project Tracking

Gitea Issue Tracker

All features, bugs, and tasks are tracked as Gitea issues with:

• Title: Clear, concise description
• Description: Detailed explanation, context, acceptance criteria
• Labels: feature, bug, enhancement, frontend, backend, P1, P2, etc.
• Assignee: Responsible team member
• Milestone: Link to project phase
• Status: Open, In Progress, Closed

Gitea Project Boards

Kanban columns:

1. Backlog: Identified but not prioritized
2. To Do: Prioritized, ready for development
3. In Progress: Currently being worked on
4. Code Review: Awaiting PR review
5. Testing: Being tested in testing environment
6. Done: Completed

Communication Channels

• Asynchronous: Gitea issues/PRs (primary for task discussions)
• Real-time: Matrix (Synapse homeserver) for quick questions
• Daily stand-ups: Virtual meetings (what done yesterday, today's plan, blockers)

Current Status

The project is production-ready with 95%+ completion:

✅ Completed

• Backend Infrastructure: Complete with 3 microservices (auth, work, payment)
• Database: Comprehensive 3-migration system with full schemas
• Authentication: Multi-factor (email/password + blockchain) with RBAC
• Frontend State Management: Four comprehensive Pinia stores
• APIs: 30+ RESTful endpoints across all services (~1,950+ lines of Go code)
• Infrastructure: Container orchestration with Podman Compose
• CI/CD: Automated testing on every commit
• Documentation: Complete deployment and operation guides
• Security: JWT authentication, password hashing, signature verification, RBAC

🏗️ In Progress

• Frontend component implementations
• Dashboard UIs
• Comprehensive E2E tests
• Production deployment configuration

📋 Remaining Work (5%)

• Full IPFS file upload/download UI
• BTCPay Server integration
• Matrix messaging integration
• Self-hosted email server
• Advanced blockchain features

Special Considerations

1. Self-Sovereignty: All infrastructure is designed to be self-hosted
2. Enterprise-Grade: Strict development workflow with comprehensive testing
3. Blockchain Integration: Ethereum-based identity and verification
4. Decentralization: IPFS integration for data resilience
5. Multi-Modal Payments: Support for traditional and cryptocurrency payments
6. Security-First: JWT authentication, encrypted communication, and role-based access
7. Production Ready: Platform is 95% complete and ready for deployment