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

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

```bash
# 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)

```bash
# 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)

```bash
# 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`:
   ```bash
   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/`:
```typescript
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."