web-hosts/domains/coppertone.tech/docs/project-plan/phases/Phase-3-Backend-Development-and-API.md

Phase 3 Breakdown: Go Backend Development & Blockchain Integration

This phase involves building the server-side logic and core data mechanisms that will power the dynamic features of the website, such as user accounts, work management, and payments. The backend will be designed as a collection of serverless Go functions, leveraging blockchain for enhanced identity and verifiable transactions, and IPFS for decentralized data storage.

Recommended Tech Stack:

• Backend Language: Go 1.25+
• Serverless Framework: Exploration of platforms like OpenFaaS, Knative, or custom Podman orchestration for Go functions.
• Database: PostgreSQL (for relational data storage where appropriate).
• ORM/Database Access: Go-specific ORMs (e.g., GORM, SQLC) or direct database/sql package.
• Blockchain Integration: Specific blockchain (e.g., Ethereum, Polygon, custom solution) and client libraries (e.g., go-ethereum).

---

Task 3.1: Go Backend Setup (Serverless-first)

We will set up the Go application as a collection of serverless functions, establishing connections to the database and exploring deployment strategies, all within a containerized environment.

• 3.1.1. Initialize Go Project(s):
  • Create a backend directory.
  • Inside, initialize a Go module: go mod init <module_path>.
  • Structure the project for individual serverless functions/microservices (e.g., backend/auth-svc, backend/work-mgmt-svc).
• 3.1.2. Database Connection:
  • Implement database connection logic using Go's database/sql package or a chosen ORM/library (e.g., GORM, SQLC).
  • Set up database migrations (e.g., using golang-migrate/migrate).
• 3.1.3. Serverless Function Development Environment:
  • Create Containerfiles for each Go serverless function, optimized for small, secure images.
  • Explore and integrate a local serverless development environment: This could involve local execution of Go functions, or using a local deployment of OpenFaaS/Knative within Podman.
• 3.1.4. Podman Compose Integration:
  • Add individual Go backend services (representing functions or microservices) to the podman-compose.yml.
  • Ensure podman-compose.yml can orchestrate these Go functions along with PostgreSQL and other services.

---

Task 3.2: User Authentication, Authorization & Multi-Factor/Blockchain Identity

A secure, decentralized, and flexible authentication system is critical for protecting user data and internal systems, allowing multiple identity options.

• 3.2.1. Database Schema (PostgreSQL):
  • User Table: id, name, email (nullable, for blockchain-only users), role.
  • Identity Table: id, user_id (FK to User), type (e.g., 'email_password', 'blockchain_address', 'did'), identifier (e.g., email address, blockchain address), credential (e.g., password hash, public key), is_primary_login (boolean).
  • Define a Role enum (e.g., ADMIN, STAFF, CLIENT).
• 3.2.2. Go API Endpoints (Auth Service - Multi-Auth Flows):
  • /register-email-password: POST endpoint to register a user with email and password.
  • /register-blockchain: POST endpoint to register a user using a blockchain address/DID (e.g., by verifying a signed message from the client-side wallet).
  • /login-email-password: POST endpoint to authenticate a user with email and password.
  • /login-blockchain: POST endpoint to authenticate a user with a blockchain address/DID (e.g., by verifying a signed message from the client-side wallet).
  • /link-identity: POST endpoint for an authenticated user to link an additional identity (email/password or blockchain address) to their existing account.
  • /unlink-identity: POST endpoint for an authenticated user to unlink an identity.
  • /profile: GET endpoint, protected by authentication, to fetch the user's profile and linked identities.
• 3.2.3. Multi-Factor & Blockchain-based Identity Implementation:
  • "Either/Or/Both" Scenario: The system will allow users to:
    • Register and log in solely with email/password.
    • Register and log in solely with a blockchain identity (e.g., Ethereum address and signature, or a DID).
    • Register with one method and link the other(s) later, allowing login via any linked identity.
  • Blockchain Signature Verification: Implement Go functions to verify cryptographic signatures from client-side wallets against registered blockchain addresses/DIDs for authentication.
  • Decentralized Identifiers (DIDs) & Verifiable Credentials (VCs):
    • Research: Evaluate frameworks and standards for implementing DIDs in Go.
    • Key Management: Implement secure generation and storage of cryptographic keys associated with blockchain identities.
    • VCs for RBAC: Explore using VCs for role-based access control, allowing users to present verifiable proofs of their roles.
• 3.2.4. JWT/Token Strategy (Go):
  • Use a Go library (e.g., github.com/golang-jwt/jwt) to handle JWT creation and verification.
  • JWT claims will be expanded to represent the various linked identities and the method of authentication used, allowing for granular authorization.
  • Implement middleware for authentication and role-based authorization for all protected API endpoints.

---

Task 3.3: Work Management & IPFS-Interchangeable API

This is the core of the internal business management tool, designed with IPFS interchangeability in mind for resilient data.

• 3.3.1. Database Schema (PostgreSQL):
  • Project: id, name, description, status (PLANNING, IN_PROGRESS, COMPLETED), clientId (relation to User), ipfs_metadata_cid (for project metadata on IPFS).
  • Task: id, title, description, status, dueDate, projectId (relation to Project), assigneeId (relation to User).
  • WorkOrder: id, title, description, projectId.
• 3.3.2. Go API Endpoints (Work Management Service):
  • Implement full CRUD (Create, Read, Update, Delete) endpoints for Projects, Tasks, and WorkOrders using Go functions.
  • /projects: GET, POST.
  • /projects/🆔 GET, PUT, DELETE.
  • /projects/:id/tasks: GET, POST.
• 3.3.3. IPFS Interchangeability Implementation (Go):
  • Integrate a Go IPFS client library (e.g., go-ipfs-api or go-libp2p-kad-dht if running a full node).
  • Implement functions to:
    • Add project documents/data to IPFS, returning a CID.
    • Pin CIDs on a local IPFS node (or a pinning service).
    • Retrieve content from IPFS using CIDs.
  • Store IPFS CIDs in the PostgreSQL database for reference to decentralized content.

---

Task 3.4: Payment Gateway & Blockchain Transactions

This API will handle invoicing and payment processing, with an emphasis on blockchain capabilities.

• 3.4.1. Database Schema (PostgreSQL):
  • Invoice: id, amount, currency, status (DRAFT, SENT, PAID, VOID), dueDate, projectId (relation to Project), blockchain_tx_hash (for on-chain payment proof).
  • Payment: id, amount, currency, paymentMethod (CREDIT_CARD, CRYPTO, BLOCKCHAIN_TOKEN), transactionId, invoiceId (relation to Invoice).
• 3.4.2. Credit Card Integration (Go):
  • Integrate the Stripe Go client library (github.com/stripe/stripe-go).
  • Create Go API endpoints to:
    • Create Stripe "Payment Intents" (/invoices/:id/create-payment-intent).
    • Handle Stripe webhooks (/stripe-webhook) to update invoice status.
• 3.4.3. Cryptocurrency Integration (Go & BTCPay Server):
  • Integrate Go client for BTCPay Server (if available, or use direct API calls).
  • Deploy BTCPay Server as a Podman service.
  • Create Go API endpoints to:
    • Generate BTCPay Server invoices (/invoices/:id/create-btcpay-invoice).
    • Process BTCPay Server webhooks.
• 3.4.4. Direct Blockchain Transaction Integration (Go):
  • Research specific blockchain(s) (e.g., EVM-compatible chains) and Go client libraries (e.g., go-ethereum).
  • Implement functionality for direct on-chain token transfers for specific services or smart contract interactions (e.g., for escrow or milestone payments).
  • Create Go API endpoints to:
    • Initiate blockchain transactions.
    • Monitor transaction status on the blockchain.
    • Update invoice/payment status based on on-chain events.