skills

TLS Watch - Project Skills

Project Overview

TLS Watch is a self-hosted TLS/SSL certificate monitoring app. It checks certificate expiry dates, sends notifications when they're about to expire, and provides a dashboard to manage everything.

Stack:

• Backend: Go (Gin, GORM, SQLite) - located in backend/
• Frontend: Next.js 14 + TypeScript + Tailwind CSS - located in frontend/
• Deployment: Docker (single container)

Directory Structure

tls-watch/
├── backend/
│   ├── main.go             # Entry point, routes
│   ├── handlers/           # HTTP handlers
│   ├── models/             # GORM models
│   ├── services/           # Business logic
│   └── pkg/                # Utilities
├── frontend/
│   ├── app/                # Next.js pages
│   ├── components/         # React components
│   │   └── ui/             # shadcn/ui
│   └── lib/                # API client, utils
├── Dockerfile
└── docker-compose.yml

Key Patterns

Modal Components

interface Props {
    project: Project;
    onClose: () => void;
}

export default function SomeModal({ project, onClose }: Props) {
    return (
        <Dialog open={true} onOpenChange={(open) => !open && onClose()}>
            <DialogContent>
                {/* Content */}
            </DialogContent>
        </Dialog>
    );
}

Confirmation Dialogs - Use ConfirmModal, NOT native confirm()

import ConfirmModal from "@/components/ConfirmModal"

const [showConfirm, setShowConfirm] = useState(false);

<ConfirmModal
    isOpen={showConfirm}
    title="Delete Item"
    message="This cannot be undone."
    onConfirm={handleDelete}
    onCancel={() => setShowConfirm(false)}
    isDestructive={true}
    confirmText="Delete"
    cancelText="Cancel"
/>

API Pattern

import api from '@/lib/api';

const res = await api.get(`/endpoint`);
await api.post(`/endpoint`, { data });
await api.delete(`/endpoint`);

Backend Handler Pattern

func HandlerName(c *gin.Context) {
    userID := c.MustGet("userID").(uint)
    paramID := c.Param("id")
    
    var model models.Model
    if err := models.DB.Where("id = ? AND user_id = ?", paramID, userID).First(&model).Error; err != nil {
        c.JSON(http.StatusNotFound, gin.H{"error": "Not found"})
        return
    }
    
    c.JSON(http.StatusOK, gin.H{"data": result})
}

Development Commands

# Docker build & run
docker-compose up --build -d
docker-compose logs -f

# Frontend dev
cd frontend && npm install && npm run dev

# Backend dev
cd backend && go run main.go

Database Models

• User - Authentication
• Project - Certificate monitoring projects
• Domain - Domains to monitor
• Notification - Notification channels (discord, slack, telegram, irc, generic)
• NotificationLog - Delivery history
• IRCAccount - IRC bot accounts
• LoginLog - User login history

Important Rules

1. Never use native confirm(), alert(), or prompt() - use ConfirmModal instead
2. Use Preload() in GORM queries for nested data
3. Backend returns paginated responses: { data: [...], total, page, total_pages }
4. Use stripIRCCodes() helper for IRC messages
5. Update README.md when adding or changing features - keep docs in sync with code
6. Commit and push after completing features - don't leave uncommitted work
7. Check for duplicate data before inserting (domains, notifications, etc.)

Git Workflow

Always commit with conventional commit messages:

feat: add notification frequency setting
fix: properly detect IRC connection failure
docs: update README with new features
refactor: simplify SSL check logic

After completing a feature or fix:

1. git add -A
2. git commit -m "type: description"
3. git push

Writing Code & Docs

DRY (Don't Repeat Yourself) - Extract repeated logic into helper functions. If you write similar code twice, refactor it.

Keep code and documentation simple and readable. No emojis in README or docs - looks AI-generated. Write like a developer: clear, practical, straight to the point.

Bad:

## 🚀 Amazing Features! ✨
We're SO excited to introduce this INCREDIBLE feature! 🎉

Good:

## Features
- SSL certificate monitoring with expiry alerts
- Multi-channel notifications (Discord, Slack, Telegram, IRC)

Keep comments minimal. If the code is clear, it doesn't need a comment.

Notification System

Notifications have status tracking:

• last_status: "success" | "failed" | "pending"
• last_error: Error message if failed

Frequency per project:

• notify_frequency: "daily" | "weekly" | "monthly"
• last_notified_at: Timestamp of last notification

Always update notification status after sending.