copper-tone-tech/web-hosts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
web-hosts/domains/coppertone.tech/CLAUDE.md
Derek Williams c7d6786039 Add full web-hosts state
2025-12-26 13:38:04 +01:00

16 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Copper Tone Technologies (Hopoyuksa Tali Lakna) platform by Amelika Okla Ilemiko is a comprehensive web platform for IT field services and emerging technology. This is an enterprise-grade, self-sovereign system with:

  • Public promotional website (Progressive Web App)
  • Internal work management system for scheduling and tracking
  • Client portal with project tracking and invoicing
  • Multi-modal payment gateway (credit cards, cryptocurrency, blockchain tokens)
  • Decentralized storage integration (IPFS via Helia frontend and IPFS-interchangeable Go backend)
  • Future integrations: Matrix messaging, self-hosted email, blockchain identity

Project Architecture

This is a monorepo with a Vue 3 PWA frontend and Go serverless backend functions, all containerized with Podman. The project emphasizes complete self-sovereignty and enterprise-grade infrastructure.

Repository Structure

coppertone.tech/
├── frontend/               # Vue 3 PWA application
│   ├── src/
│   │   ├── views/         # Page-level components
│   │   ├── components/    # Reusable components (ui/, layout/, views/)
│   │   ├── stores/        # Pinia state management
│   │   └── router/        # Vue Router configuration
│   └── public/            # Static assets, service worker
├── backend/
│   └── functions/         # Independent Go microservices
│       ├── auth-service/  # JWT auth, user registration/login
│       └── work-management-service/  # Work tracking (in progress)
├── docs/
│   └── project-plan/      # Comprehensive project documentation
│       ├── phases/        # Detailed phase breakdowns
│       └── Git-Workflow.md # Enterprise Git workflow (MUST READ)
└── podman-compose.yml     # Container orchestration

Technology Stack

Frontend:

  • Vue 3 (Composition API) with TypeScript
  • Vue Router 4 (route-level code splitting)
  • Pinia (state management)
  • Tailwind CSS 4 (utility-first styling)
  • Vite (build tool)
  • Vitest (unit tests), Cypress (E2E tests)
  • markdown-it + gray-matter (Markdown content)
  • Progressive Web App (PWA) capabilities

Backend:

  • Go 1.25+ (serverless HTTP handlers)
  • PostgreSQL 16 (database)
  • JWT authentication (golang-jwt/jwt)
  • bcrypt password hashing
  • Each service is independent with own main.go, go.mod, Containerfile

Infrastructure:

  • Podman/podman-compose for containerization
  • Self-hosted Gitea with Gitea Actions (CI/CD)
  • Future: IPFS (Helia frontend, IPFS-interchangeable backend), Matrix, self-hosted email

Development Commands

Frontend (from /frontend directory)

# Development server (hot reload)
npm run dev

# Build for production
npm run build

# Type checking
npm run type-check

# Linting (auto-fix)
npm run lint

# Format code
npm run format

# Unit tests (watch mode)
npm run test:unit

# E2E tests (headless)
npm run test:e2e

# E2E tests (interactive)
npm run test:e2e:dev

# Preview production build
npm run preview

Node Requirements: Node.js ^20.19.0 || >=22.12.0

Backend (from /backend/functions/<service-name> directory)

# Run service locally
go run main.go

# Build binary
go build -o service main.go

# Run tests
go test ./...

# Format code
go fmt ./...

# Update dependencies
go mod tidy

Go Requirements: Go 1.25+

Container Operations (from repository root)

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

# Start services (detached)
podman-compose up -d

# Stop all services
podman-compose down

# View logs
podman-compose logs -f [service-name]

# Rebuild specific service
podman-compose build [service-name]

Services: frontend (port 8080), auth-service (port 8082), work-management-service (port 8083), db (PostgreSQL)

Git Workflow (CRITICAL - MUST FOLLOW)

This project follows a strict enterprise GitFlow model with mandatory PR reviews and automated CI checks. Read docs/project-plan/Git-Workflow.md for full details.

Branch Structure

  • 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: 
    git checkout develop
git pull
git checkout -b feature/my-feature
  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 (Gitea Actions):
    • Linting (ESLint frontend, go fmt backend)
    • Type checking (vue-tsc)
    • Unit tests (Vitest, go test)
    • E2E tests (Cypress)
  6. Code review (optional but recommended)
  7. Merge after approval and ALL CI checks pass (use "Squash and Merge")
  8. Release flow: develop → testing (via PR) → main (via PR)

Never commit directly to main, testing, or develop. All changes MUST go through PRs.

CI/CD Pipeline

  • PRs to develop trigger full test suite
  • Merge to testing deploys to staging environment
  • Merge to main deploys to production and creates version tag (e.g., v1.0.0)

Backend Service Architecture

The backend is designed as serverless-first Go microservices. Each service is an independent HTTP server with:

  • Environment-based configuration (via os.Getenv)
  • Database connection (PostgreSQL via lib/pq)
  • RESTful JSON endpoints
  • Standard internal port: 8080 (mapped to different external ports in podman-compose.yml)
  • Multi-stage Docker builds for small, secure container images

Current Services

Auth Service (port 8082)

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

Planned 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)

Current implementation: Basic email/password auth with JWT, user registration, bcrypt password hashing.

Environment Variables:

  • JWT_SECRET: Secret key for JWT signing (NEVER commit to repo)
  • DB_HOST, DB_USER, DB_PASSWORD, DB_NAME: PostgreSQL connection

Database Schema:

  • users table: id, email, password_hash, name, role, blockchain_address
  • Future: identities table for multi-auth support

Work Management Service (port 8083)

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

Status: Placeholder (minimal implementation)

Planned endpoints:

  • /projects: GET (list), POST (create)
  • /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.

Adding New Backend Services

  1. Create directory: backend/functions/<service-name>/
  2. Add main.go with HTTP handlers
  3. Initialize Go module: go mod init coppertone.tech/backend/<service-name>
  4. Add dependencies: go get packages, then go mod tidy
  5. Create multi-stage Containerfile:
    • Build stage: golang:1.25-alpine, compile binary
    • Runtime stage: alpine or scratch with only the binary
  6. Update podman-compose.yml:
    • Add service definition
    • Map external port (8084+)
    • Add environment variables
    • Add database dependency if needed
  7. Update Gitea Actions workflows for testing/deployment

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

Routes use code-splitting: each view generates separate chunk.

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/. Use Composition API pattern with defineStore.

Styling

Tailwind CSS 4 with PostCSS. Configuration in tailwind.config.js and postcss.config.js.

Path Aliases

Vite configured with @ alias pointing to src/:

import MyComponent from '@/components/MyComponent.vue'

Database

PostgreSQL 16 running in container. Schema managed manually (no ORM). Connection details in podman-compose.yml.

Default credentials (DEV ONLY):

  • Database: coppertone_db
  • User: user
  • Password: password
  • Host: db (container name)

CI/CD

Gitea Actions configured in .gitea/workflows/. Current workflow: build-frontend.yml.

PRs trigger automated:

  1. Linting (ESLint for frontend, go fmt for backend)
  2. Type checking (vue-tsc)
  3. Unit tests (Vitest for frontend, go test for backend)
  4. E2E tests (Cypress)

All checks must pass before merge.

Team Collaboration & Project Tracking

Primary tool: Self-hosted Gitea issue tracker and project boards (Kanban).

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 (e.g., "Phase 1 Completion")
  • 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

Task Workflow

  1. Select task from "To Do"
  2. Create feature/bugfix branch (link to Gitea issue)
  3. Move issue to "In Progress"
  4. Provide regular updates in issue comments (daily updates, blockers)
  5. Open PR when ready (reference issue number)
  6. After PR merge to develop, move to "Testing"
  7. Close issue when fully tested and verified

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)

Development Phases & Project Plan

Timeline: 16 two-week sprints (32 weeks estimated)

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) 🔄 IN PROGRESS

  • 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)

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

Phase 5: Advanced Features (Sprints 13-15)

  • 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)

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

Milestones:

  • Milestone 1 (Sprint 2): Infrastructure complete
  • Milestone 2 (Sprint 5): Public PWA complete
  • Milestone 3 (Sprint 9): Backend API functional
  • Milestone 4 (Sprint 12): Portals functional
  • Milestone 5 (Sprint 15): Advanced features integrated
  • Milestone 6 (Sprint 16): Launch

Documentation

  • README.md: Project overview and key features
  • GEMINI.md: Historical context (originally for Gemini Agent)
  • docs/project-plan/Plan.md: Master project plan with objectives and tech stack
  • docs/project-plan/Git-Workflow.md: CRITICAL - Enterprise Git workflow details
  • docs/project-plan/Team-Collaboration-and-Tracking.md: Collaboration guidelines
  • docs/project-plan/phases/Phase-*.md: Detailed phase breakdowns with subtasks

Important Notes & Best Practices

Security

  • NEVER commit secrets: JWT_SECRET, database passwords, API keys, private keys
  • Use environment variables for all sensitive configuration
  • Change default database credentials in production
  • Implement proper input validation and sanitization
  • Use bcrypt for password hashing (already implemented in auth-service)
  • Verify blockchain signatures for identity authentication

Testing Requirements

  • Frontend: Write unit tests (Vitest) for all new components and utilities
  • Backend: Write tests using Go's testing package (go test)
  • E2E: Add Cypress tests for critical user flows
  • All tests MUST pass before PR merge

Code Quality

  • TypeScript: Frontend uses TypeScript. Run npm run type-check before committing
  • Linting: Run npm run lint (frontend) and go fmt (backend) before pushing
  • Formatting: Use Prettier for frontend (npm run format)
  • Code Review: Review PRs for security issues, code quality, and architectural alignment

Development Practices

  • Container-First: All services run in containers. Test locally with podman-compose up
  • Database Migrations: Use golang-migrate/migrate for Go services
  • API Design: RESTful JSON APIs, consistent error handling
  • IPFS Integration: Store CIDs in PostgreSQL, content on IPFS
  • Blockchain: Research DIDs, VCs, and signature verification for identity features
  • Markdown Content: Services and blog content managed as Markdown with frontmatter (gray-matter)
  • PWA: Maintain service worker, offline capabilities, installability

Multi-Factor Authentication Architecture

The auth system supports "either/or/both" scenarios:

  • Users can register/login with email/password only
  • Users can register/login with blockchain identity only (signature verification)
  • Users can link multiple identities to one account
  • Future: Implement full DID/VC support for decentralized identity
  • "Always and only run everything, from development, testing and production code in podman/podman compose"
  • "develop is our primary development branch. whenever we work on something new, fix something, or what not, any coding, we need a feature, bugfix, issue, etc branch and once verified working, we need to either merge to develop or PR."
Reference in New Issue View Git Blame Copy Permalink