Slack Invite Manager - Claude Code Instructions

Project Overview

This is a Go-based Slack invite management application with a React TypeScript frontend. The application integrates with Google Sheets for data import/export and includes email notifications via SMTP2Go.

Project Structure

.
├── backend/              # Backend Go application
│   ├── cmd/             # Main applications
│   │   ├── server/      # Main API server
│   │   └── sheets/      # Google Sheets integration tool
│   ├── internal/        # Private application code
│   │   ├── api/        # API handlers and routes
│   │   ├── config/     # Configuration management
│   │   ├── logger/     # Structured logging (slog)
│   │   ├── models/     # Data models
│   │   └── services/   # Business logic
│   ├── pkg/            # Public library code
│   ├── test/           # Additional test files
│   ├── Dockerfile      # Backend API Dockerfile
│   └── Dockerfile.sheets  # Sheets service Dockerfile
├── web/                # Frontend React application
│   ├── src/           # React source code
│   │   ├── components/ # React components (including ErrorBoundary)
│   │   └── utils/      # Utilities (including logger)
│   ├── public/        # Static assets
│   ├── Dockerfile     # Production web Dockerfile
│   └── Dockerfile.dev # Development web Dockerfile
├── .github/           # GitHub Actions workflows
├── data/              # Local data storage (SQLite)
├── docker-compose.yml           # Development environment
├── docker-compose.app.yml       # Production app services
├── docker-compose.sheets.yml    # Production sheets service
└── README.md         # Project documentation

Technology Stack

Backend

Language: Go 1.22+
Database: SQLite (local storage)
Key Dependencies:
- ```
google.golang.org/api
```
  - Google Sheets API integration
- ```
golang.org/x/oauth2
```
  - OAuth2 authentication
Architecture: Standard Go project layout with clean separation of concerns

Frontend

Framework: React 19+ with TypeScript 5.9+
Styling: Tailwind CSS v4 (via Vite plugin)
Testing: Vitest and React Testing Library
Build Tool: Vite

Infrastructure

Containerization: Docker with multi-service docker-compose
Web Server: Nginx (static file serving in production)
SSL: Let's Encrypt
CI/CD: GitHub Actions with automated testing and deployment
Email: SMTP2Go for notifications
Logging: Structured JSON logging via Go
```
log/slog
```
(Loki-compatible)
Monitoring: Grafana with Loki for log aggregation

Coding Standards

Go Standards

Use Go 1.22+ features and idioms
Follow
```
gofmt
```
,
```
golint
```
, and
```
govet
```
guidelines
Use explicit error handling (no silent ignores)
Implement interfaces where appropriate
Use dependency injection for better testability
Keep functions small and focused
Use meaningful variable and function names
Document all exported functions and types
Use table-driven tests following AAA (Arrange-Act-Assert) pattern
Mock external dependencies in tests

React/TypeScript Standards

Use functional components with hooks
Use TypeScript for all components with proper prop typing
Keep components small and focused
Implement error boundaries where appropriate
Use React Testing Library for component tests
Follow best practices for state management
Prefer composition over inheritance
Use Tailwind CSS for styling (utility-first approach)

Testing Standards

Write unit tests for all business logic
Use table-driven tests in Go
Follow AAA (Arrange-Act-Assert) pattern
Mock external dependencies
Aim for high test coverage of critical paths
Use
```
testing
```
package for Go tests
Use Vitest and React Testing Library for frontend tests

Run tests:

# Backend tests
cd backend && go test ./...

# Frontend tests
cd web && npm test

Security Standards

Never commit secrets or credentials
Use environment variables for configuration
Sanitize all user input
Implement proper authentication and authorization
Follow OWASP security guidelines
Use HTTPS for all communications
Implement rate limiting
Use prepared statements for database queries

Development Workflow

Local Development Setup

Prerequisites:
- Go 1.22+
- Node.js 24+
- Docker and docker-compose
- Google Cloud project with Sheets API enabled
- Google service account credentials

Environment Variables (create

.env

file):

GOOGLE_CREDENTIALS_FILE="path/to/credentials.json"
GOOGLE_SPREADSHEET_ID="your-spreadsheet-id"
GOOGLE_SHEET_NAME="Sheet1"
EMAIL_RECIPIENT="[email protected]"
SMTP2GO_FROM_EMAIL="[email protected]"
SMTP2GO_USERNAME="your-smtp2go-username"
SMTP2GO_PASSWORD="your-smtp2go-api-key"
GITHUB_USERNAME="your-github-username"
LOG_LEVEL="info"  # Options: debug, info, warn, error

Start Development Environment:
```
docker compose up
```
- Frontend: http://localhost:3000 (with hot-reloading)
- Backend API: http://localhost:8080

Production Deployment

Application runs on Ubuntu home server
Docker containers for all services

Uses pre-built images from GitHub Container Registry:

ghcr.io/<username>/slack-invite-mgr-backend

- Backend API

```
ghcr.io/<username>/slack-invite-mgr-web
```
- Frontend web

ghcr.io/<username>/slack-invite-mgr-sheets

- Sheets service

Start production services:

# Main application (API + Web)
docker compose -f docker-compose.app.yml up -d

# Sheets service
docker compose -f docker-compose.sheets.yml up -d

CI/CD Pipeline

GitHub Actions workflows handle CI/CD
Automated testing on pull requests
Automated building and publishing of Docker images
Images pushed to GitHub Container Registry
Deployment to home server (requires manual trigger or automated webhook)

Key Configuration Files

```
.env
```
/
```
.env.example
```
- Environment variable templates
```
.github/workflows/
```
- CI/CD pipeline definitions
```
docker-compose.yml
```
- Development environment orchestration
```
docker-compose.app.yml
```
- Production app services
```
docker-compose.sheets.yml
```
- Production sheets service
```
backend/Dockerfile
```
- Backend API container definition
```
backend/Dockerfile.sheets
```
- Sheets service container definition
```
web/Dockerfile
```
- Frontend production container
```
web/Dockerfile.dev
```
- Frontend development container
```
web/nginx.conf.template
```
- Nginx configuration template (static file serving only)
```
web/public/config.js
```
- Runtime configuration template (generated at container startup with
```
PUBLIC_URL
```
and
```
API_URL
```
)
```
backend/go.mod
```
- Go dependencies
```
web/package.json
```
- Node.js dependencies

Common Development Tasks

Adding New API Endpoints

Define handler in
```
backend/internal/api/handlers.go
```
Add route in
```
backend/internal/api/router.go
```
Implement business logic in
```
backend/internal/services/
```
Add tests in
```
*_test.go
```
files
Update API documentation

Adding New Frontend Components

Create component in
```
web/src/components/
```
Use TypeScript with proper prop types
Apply Tailwind CSS for styling
Add tests using React Testing Library
Import and use in parent components

Working with Google Sheets

Service code is in
```
backend/internal/services/sheets.go
```
Configuration in
```
backend/internal/config/sheets.go
```
Separate sheets integration tool in
```
backend/cmd/sheets/
```

Database Changes

SQLite database stored in
```
data/
```
directory
Schema changes should be handled carefully
Regular backups are automated in production

Monitoring and Maintenance

Structured Logging

All backend services use structured JSON logging via Go's

log/slog

package, optimized for Grafana Loki:

Log Format:

{
  "time": "2026-01-03T10:15:30.123Z",
  "level": "INFO",
  "app": "slack-invite-api",
  "msg": "request completed",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "method": "GET",
  "path": "/api/invites",
  "status": 200,
  "duration": "45.2ms"
}

Configuration:

Set
```
LOG_LEVEL
```
environment variable:
```
debug
```
,
```
info
```
,
```
warn
```
,
```
error
```
(default:
```
info
```
)
Logs output to stdout for container log collection
Request logging middleware adds request IDs and timing

Key Files:

```
backend/internal/logger/logger.go
```
- Logger initialization
```
backend/internal/api/middleware.go
```
- Request logging middleware

Frontend Logging

Frontend errors are captured and sent to the backend for centralized logging in Loki.

How it works:

```
web/src/utils/logger.ts
```
provides structured logging functions
Error and warn level logs are sent to
```
POST /api/logs
```
endpoint
Backend logs them with
```
app: "slack-invite-web"
```
identifier
ErrorBoundary catches React component crashes

Frontend Log Entry:

{
  "level": "error",
  "message": "Failed to update invite statuses",
  "context": {
    "error": "Network request failed",
    "operation": "mark_sent",
    "emailCount": 5
  }
}

Key Files:

```
web/src/utils/logger.ts
```
- Frontend logger utility
```
web/src/components/ErrorBoundary.tsx
```
- React error boundary

backend/internal/api/handlers.go

FrontendLogsHandler

endpoint

General Maintenance

Application logs are collected and monitored via Grafana/Loki
Error tracking and alerting configured
Regular security updates required
Automated database backups in production
Cron jobs for maintenance tasks (sheets sync, etc.)

Important Notes

Hot reloading is enabled for both Go and React in development
Source code is mounted in development containers for live updates
Production uses optimized builds from GitHub Container Registry
Frontend serves on port 80 in production, port 3000 in development
Backend API always on port 8080
Database is SQLite for both dev and production (in
```
data/
```
directory)
Subpath deployment is fully configurable at runtime via
```
PUBLIC_URL
```
environment variable - no rebuild required
API URL is configured via
```
API_URL
```
environment variable - must be browser-accessible (not internal docker hostname)
Frontend makes direct API calls - nginx does not proxy API requests, making the container portable for k8s deployments

Getting Help

See
```
README.md
```
for detailed setup instructions
Check
```
.github/workflows/
```
for CI/CD pipeline details
Review existing tests for examples of testing patterns
Consult Go and React documentation for framework-specific questions

Slack Invite Manager - Claude Code Instructions

Project Overview

Project Structure

.
├── backend/              # Backend Go application
│   ├── cmd/             # Main applications
│   │   ├── server/      # Main API server
│   │   └── sheets/      # Google Sheets integration tool
│   ├── internal/        # Private application code
│   │   ├── api/        # API handlers and routes
│   │   ├── config/     # Configuration management
│   │   ├── logger/     # Structured logging (slog)
│   │   ├── models/     # Data models
│   │   └── services/   # Business logic
│   ├── pkg/            # Public library code
│   ├── test/           # Additional test files
│   ├── Dockerfile      # Backend API Dockerfile
│   └── Dockerfile.sheets  # Sheets service Dockerfile
├── web/                # Frontend React application
│   ├── src/           # React source code
│   │   ├── components/ # React components (including ErrorBoundary)
│   │   └── utils/      # Utilities (including logger)
│   ├── public/        # Static assets
│   ├── Dockerfile     # Production web Dockerfile
│   └── Dockerfile.dev # Development web Dockerfile
├── .github/           # GitHub Actions workflows
├── data/              # Local data storage (SQLite)
├── docker-compose.yml           # Development environment
├── docker-compose.app.yml       # Production app services
├── docker-compose.sheets.yml    # Production sheets service
└── README.md         # Project documentation

Technology Stack

Backend

Language: Go 1.22+
Database: SQLite (local storage)
Key Dependencies:
- ```
google.golang.org/api
```
  - Google Sheets API integration
- ```
golang.org/x/oauth2
```
  - OAuth2 authentication
Architecture: Standard Go project layout with clean separation of concerns

Frontend

Framework: React 19+ with TypeScript 5.9+
Styling: Tailwind CSS v4 (via Vite plugin)
Testing: Vitest and React Testing Library
Build Tool: Vite

Infrastructure

Containerization: Docker with multi-service docker-compose
Web Server: Nginx (static file serving in production)
SSL: Let's Encrypt
CI/CD: GitHub Actions with automated testing and deployment
Email: SMTP2Go for notifications
Logging: Structured JSON logging via Go
```
log/slog
```
(Loki-compatible)
Monitoring: Grafana with Loki for log aggregation

Coding Standards

Go Standards

Use Go 1.22+ features and idioms
Follow
```
gofmt
```
,
```
golint
```
, and
```
govet
```
guidelines
Use explicit error handling (no silent ignores)
Implement interfaces where appropriate
Use dependency injection for better testability
Keep functions small and focused
Use meaningful variable and function names
Document all exported functions and types
Use table-driven tests following AAA (Arrange-Act-Assert) pattern
Mock external dependencies in tests

React/TypeScript Standards

Use functional components with hooks
Use TypeScript for all components with proper prop typing
Keep components small and focused
Implement error boundaries where appropriate
Use React Testing Library for component tests
Follow best practices for state management
Prefer composition over inheritance
Use Tailwind CSS for styling (utility-first approach)

Testing Standards

Write unit tests for all business logic
Use table-driven tests in Go
Follow AAA (Arrange-Act-Assert) pattern
Mock external dependencies
Aim for high test coverage of critical paths
Use
```
testing
```
package for Go tests
Use Vitest and React Testing Library for frontend tests

Run tests:

# Backend tests
cd backend && go test ./...

# Frontend tests
cd web && npm test

Security Standards

Never commit secrets or credentials
Use environment variables for configuration
Sanitize all user input
Implement proper authentication and authorization
Follow OWASP security guidelines
Use HTTPS for all communications
Implement rate limiting
Use prepared statements for database queries

Development Workflow

Local Development Setup

Prerequisites:
- Go 1.22+
- Node.js 24+
- Docker and docker-compose
- Google Cloud project with Sheets API enabled
- Google service account credentials

Environment Variables (create

.env

file):

GOOGLE_CREDENTIALS_FILE="path/to/credentials.json"
GOOGLE_SPREADSHEET_ID="your-spreadsheet-id"
GOOGLE_SHEET_NAME="Sheet1"
EMAIL_RECIPIENT="[email protected]"
SMTP2GO_FROM_EMAIL="[email protected]"
SMTP2GO_USERNAME="your-smtp2go-username"
SMTP2GO_PASSWORD="your-smtp2go-api-key"
GITHUB_USERNAME="your-github-username"
LOG_LEVEL="info"  # Options: debug, info, warn, error

Start Development Environment:
```
docker compose up
```
- Frontend: http://localhost:3000 (with hot-reloading)
- Backend API: http://localhost:8080

Production Deployment

Application runs on Ubuntu home server
Docker containers for all services

Uses pre-built images from GitHub Container Registry:

ghcr.io/<username>/slack-invite-mgr-backend

- Backend API

```
ghcr.io/<username>/slack-invite-mgr-web
```
- Frontend web

ghcr.io/<username>/slack-invite-mgr-sheets

- Sheets service

Start production services:

# Main application (API + Web)
docker compose -f docker-compose.app.yml up -d

# Sheets service
docker compose -f docker-compose.sheets.yml up -d

CI/CD Pipeline

GitHub Actions workflows handle CI/CD
Automated testing on pull requests
Automated building and publishing of Docker images
Images pushed to GitHub Container Registry
Deployment to home server (requires manual trigger or automated webhook)

Key Configuration Files

```
.env
```
/
```
.env.example
```
- Environment variable templates
```
.github/workflows/
```
- CI/CD pipeline definitions
```
docker-compose.yml
```
- Development environment orchestration
```
docker-compose.app.yml
```
- Production app services
```
docker-compose.sheets.yml
```
- Production sheets service
```
backend/Dockerfile
```
- Backend API container definition
```
backend/Dockerfile.sheets
```
- Sheets service container definition
```
web/Dockerfile
```
- Frontend production container
```
web/Dockerfile.dev
```
- Frontend development container
```
web/nginx.conf.template
```
- Nginx configuration template (static file serving only)
```
web/public/config.js
```
- Runtime configuration template (generated at container startup with
```
PUBLIC_URL
```
and
```
API_URL
```
)
```
backend/go.mod
```
- Go dependencies
```
web/package.json
```
- Node.js dependencies

Common Development Tasks

Adding New API Endpoints

Define handler in
```
backend/internal/api/handlers.go
```
Add route in
```
backend/internal/api/router.go
```
Implement business logic in
```
backend/internal/services/
```
Add tests in
```
*_test.go
```
files
Update API documentation

Adding New Frontend Components

Create component in
```
web/src/components/
```
Use TypeScript with proper prop types
Apply Tailwind CSS for styling
Add tests using React Testing Library
Import and use in parent components

Working with Google Sheets

Service code is in
```
backend/internal/services/sheets.go
```
Configuration in
```
backend/internal/config/sheets.go
```
Separate sheets integration tool in
```
backend/cmd/sheets/
```

Database Changes

SQLite database stored in
```
data/
```
directory
Schema changes should be handled carefully
Regular backups are automated in production

Monitoring and Maintenance

Structured Logging

All backend services use structured JSON logging via Go's

log/slog

package, optimized for Grafana Loki:

Log Format:

{
  "time": "2026-01-03T10:15:30.123Z",
  "level": "INFO",
  "app": "slack-invite-api",
  "msg": "request completed",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "method": "GET",
  "path": "/api/invites",
  "status": 200,
  "duration": "45.2ms"
}

Configuration:

Set
```
LOG_LEVEL
```
environment variable:
```
debug
```
,
```
info
```
,
```
warn
```
,
```
error
```
(default:
```
info
```
)
Logs output to stdout for container log collection
Request logging middleware adds request IDs and timing

Key Files:

```
backend/internal/logger/logger.go
```
- Logger initialization
```
backend/internal/api/middleware.go
```
- Request logging middleware

Frontend Logging

Frontend errors are captured and sent to the backend for centralized logging in Loki.

How it works:

```
web/src/utils/logger.ts
```
provides structured logging functions
Error and warn level logs are sent to
```
POST /api/logs
```
endpoint
Backend logs them with
```
app: "slack-invite-web"
```
identifier
ErrorBoundary catches React component crashes

Frontend Log Entry:

{
  "level": "error",
  "message": "Failed to update invite statuses",
  "context": {
    "error": "Network request failed",
    "operation": "mark_sent",
    "emailCount": 5
  }
}

Key Files:

```
web/src/utils/logger.ts
```
- Frontend logger utility
```
web/src/components/ErrorBoundary.tsx
```
- React error boundary

backend/internal/api/handlers.go

FrontendLogsHandler

endpoint

General Maintenance

Application logs are collected and monitored via Grafana/Loki
Error tracking and alerting configured
Regular security updates required
Automated database backups in production
Cron jobs for maintenance tasks (sheets sync, etc.)

Important Notes

Hot reloading is enabled for both Go and React in development
Source code is mounted in development containers for live updates
Production uses optimized builds from GitHub Container Registry
Frontend serves on port 80 in production, port 3000 in development
Backend API always on port 8080
Database is SQLite for both dev and production (in
```
data/
```
directory)
Subpath deployment is fully configurable at runtime via
```
PUBLIC_URL
```
environment variable - no rebuild required
API URL is configured via
```
API_URL
```
environment variable - must be browser-accessible (not internal docker hostname)
Frontend makes direct API calls - nginx does not proxy API requests, making the container portable for k8s deployments

Getting Help

See
```
README.md
```
for detailed setup instructions
Check
```
.github/workflows/
```
for CI/CD pipeline details
Review existing tests for examples of testing patterns
Consult Go and React documentation for framework-specific questions

Slack Invite Manager - Claude Code Instructions

Related Skills

Nano Banana Pro

Markdown Converter

1password