404 lines
16 KiB
Markdown
404 lines
16 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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 |