DiunDashboard/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-03-23

Directory Layout

DiunDashboard/
├── cmd/
│   └── diunwebhook/
│       └── main.go              # Application entry point
├── pkg/
│   └── diunwebhook/
│       ├── diunwebhook.go       # Core library: types, DB, handlers
│       ├── diunwebhook_test.go  # Tests (external test package)
│       └── export_test.go       # Test-only exports
├── frontend/
│   ├── src/
│   │   ├── main.tsx             # React entry point
│   │   ├── App.tsx              # Root component (layout, state wiring)
│   │   ├── index.css            # Tailwind CSS base styles
│   │   ├── vite-env.d.ts        # Vite type declarations
│   │   ├── components/
│   │   │   ├── Header.tsx       # Top nav bar with refresh button
│   │   │   ├── TagSection.tsx   # Droppable tag group container
│   │   │   ├── ServiceCard.tsx  # Individual image/service card (draggable)
│   │   │   ├── AcknowledgeButton.tsx  # Dismiss/acknowledge button
│   │   │   └── ui/             # shadcn/ui primitives
│   │   │       ├── badge.tsx
│   │   │       ├── button.tsx
│   │   │       ├── card.tsx
│   │   │       └── tooltip.tsx
│   │   ├── hooks/
│   │   │   ├── useUpdates.ts    # Polling, acknowledge, tag assignment
│   │   │   └── useTags.ts      # Tag CRUD operations
│   │   ├── lib/
│   │   │   ├── utils.ts         # cn() class merge utility
│   │   │   ├── time.ts          # timeAgo() relative time formatter
│   │   │   ├── serviceIcons.ts  # Map Docker image names to simple-icons
│   │   │   └── serviceIcons.json  # Image name -> icon slug mapping
│   │   └── types/
│   │       └── diun.ts          # TypeScript interfaces (DiunEvent, UpdateEntry, Tag, UpdatesMap)
│   ├── public/
│   │   └── favicon.svg
│   ├── index.html               # SPA HTML shell
│   ├── package.json             # Frontend dependencies
│   ├── vite.config.ts           # Vite build + dev proxy config
│   ├── tailwind.config.ts       # Tailwind theme configuration
│   ├── tsconfig.json            # TypeScript project references
│   ├── tsconfig.app.json        # App TypeScript config
│   ├── tsconfig.node.json       # Node/Vite TypeScript config
│   ├── postcss.config.js        # PostCSS/Tailwind pipeline
│   └── components.json          # shadcn/ui component config
├── docs/
│   ├── index.md                 # VitePress docs homepage
│   ├── guide/
│   │   └── index.md             # Getting started guide
│   ├── package.json             # Docs site dependencies
│   ├── Dockerfile               # Docs site Nginx container
│   ├── nginx.conf               # Docs site Nginx config
│   └── .gitignore               # Ignore docs build artifacts
├── .claude/
│   └── CLAUDE.md                # Claude Code project instructions
├── .gitea/
│   └── workflows/
│       ├── ci.yml               # CI pipeline (test + build)
│       └── release.yml          # Release/deploy pipeline
├── .planning/
│   └── codebase/                # GSD codebase analysis documents
├── Dockerfile                   # Multi-stage build (frontend + Go + runtime)
├── compose.yml                  # Docker Compose for deployment (pulls image)
├── compose.dev.yml              # Docker Compose for local dev (builds locally)
├── go.mod                       # Go module definition
├── go.sum                       # Go dependency checksums
├── .gitignore                   # Git ignore rules
├── README.md                    # Project readme
├── CONTRIBUTING.md              # Developer guide
└── LICENSE                      # License file

Directory Purposes

cmd/diunwebhook/:

• Purpose: Application binary entry point
• Contains: Single main.go file
• Key files: cmd/diunwebhook/main.go

pkg/diunwebhook/:

• Purpose: Core library containing all backend logic (types, database, HTTP handlers)
• Contains: One implementation file, one test file, one test-exports file
• Key files: pkg/diunwebhook/diunwebhook.go, pkg/diunwebhook/diunwebhook_test.go, pkg/diunwebhook/export_test.go

frontend/src/components/:

• Purpose: React UI components
• Contains: Feature components (Header, TagSection, ServiceCard, AcknowledgeButton) and ui/ subdirectory with shadcn/ui primitives

frontend/src/components/ui/:

• Purpose: Reusable UI primitives from shadcn/ui
• Contains: badge.tsx, button.tsx, card.tsx, tooltip.tsx
• Note: These are generated/copied from shadcn/ui CLI and customized via components.json

frontend/src/hooks/:

• Purpose: Custom React hooks encapsulating data fetching and state management
• Contains: useUpdates.ts (polling, acknowledge, tag assignment), useTags.ts (tag CRUD)

frontend/src/lib/:

• Purpose: Shared utility functions and data
• Contains: utils.ts (Tailwind class merge), time.ts (relative time), serviceIcons.ts + serviceIcons.json (Docker image icon lookup)

frontend/src/types/:

• Purpose: TypeScript type definitions shared across the frontend
• Contains: diun.ts with interfaces matching Go backend structs

docs/:

• Purpose: VitePress documentation site (separate from main app)
• Contains: Markdown content, VitePress config, Dockerfile for static deployment
• Build output: docs/.vitepress/dist/ (gitignored)

.gitea/workflows/:

• Purpose: CI/CD pipeline definitions for Gitea Actions
• Contains: ci.yml (test + build), release.yml (release/deploy)

Key File Locations

Entry Points:

• cmd/diunwebhook/main.go: Go server entry point -- init DB, register routes, start server
• frontend/src/main.tsx: React SPA mount point -- renders <App /> into DOM, enables dark mode

Configuration:

• go.mod: Go module awesomeProject, Go 1.26, SQLite dependency
• frontend/vite.config.ts: Vite build config, @ path alias to src/, dev proxy for /api and /webhook to :8080
• frontend/tailwind.config.ts: Tailwind CSS theme customization
• frontend/components.json: shadcn/ui component generation config
• frontend/tsconfig.json: TypeScript project references (app + node configs)
• Dockerfile: Multi-stage build (Bun frontend build, Go binary build, Alpine runtime)
• compose.yml: Production deployment config (pulls from gitea.jeanlucmakiola.de registry)
• compose.dev.yml: Local development config (builds from Dockerfile)

Core Logic:

• pkg/diunwebhook/diunwebhook.go: ALL backend logic -- struct definitions, database init/migrations, event storage, all 6 HTTP handlers
• frontend/src/App.tsx: Root component -- stat cards, tag section rendering, drag-and-drop context, new group creation UI
• frontend/src/hooks/useUpdates.ts: Primary data hook -- 5s polling, acknowledge, tag assignment with optimistic updates
• frontend/src/hooks/useTags.ts: Tag management hook -- fetch, create, delete

Testing:

• pkg/diunwebhook/diunwebhook_test.go: All backend tests (external test package diunwebhook_test)
• pkg/diunwebhook/export_test.go: Exports internal functions for testing (GetUpdatesMap, UpdatesReset, ResetTags, ResetWebhookSecret)

Naming Conventions

Files:

• Go: lowercase, single word or underscore-separated (diunwebhook.go, export_test.go)
• React components: PascalCase (ServiceCard.tsx, TagSection.tsx)
• Hooks: camelCase prefixed with use (useUpdates.ts, useTags.ts)
• Utilities: camelCase (time.ts, utils.ts)
• shadcn/ui primitives: lowercase (badge.tsx, button.tsx)

Directories:

• Go: lowercase (cmd/, pkg/)
• Frontend: lowercase (components/, hooks/, lib/, types/, ui/)

Where to Add New Code

New API Endpoint:

• Add handler function to pkg/diunwebhook/diunwebhook.go
• Register route in cmd/diunwebhook/main.go on the mux
• Add tests in pkg/diunwebhook/diunwebhook_test.go
• If new test helpers are needed, add exports in pkg/diunwebhook/export_test.go

New Database Table or Migration:

• Add CREATE TABLE IF NOT EXISTS or ALTER TABLE in InitDB() in pkg/diunwebhook/diunwebhook.go
• Follow existing pattern: CREATE TABLE IF NOT EXISTS for new tables, silent ALTER TABLE for column additions

New React Component:

• Feature component: frontend/src/components/YourComponent.tsx
• Reusable UI primitive: frontend/src/components/ui/yourprimitive.tsx (use shadcn/ui CLI or follow existing pattern)

New Custom Hook:

• Place in frontend/src/hooks/useYourHook.ts
• Follow pattern from useUpdates.ts: export a function returning state and callbacks

New TypeScript Type:

• Add to frontend/src/types/diun.ts if related to the DIUN domain
• Create new file in frontend/src/types/ for unrelated domains

New Utility Function:

• Add to frontend/src/lib/ in an existing file or new file by domain
• Time-related: frontend/src/lib/time.ts
• CSS/styling: frontend/src/lib/utils.ts

New Go Package:

• Create under pkg/yourpackage/ following Go conventions
• Import from awesomeProject/pkg/yourpackage (module name is awesomeProject)

Special Directories

frontend/dist/:

• Purpose: Production build output served by Go file server at /
• Generated: Yes, by bun run build in frontend/
• Committed: No (gitignored)

docs/.vitepress/dist/:

• Purpose: Documentation site build output
• Generated: Yes, by bun run build in docs/
• Committed: No (gitignored)

.planning/codebase/:

• Purpose: GSD codebase analysis documents for AI-assisted development
• Generated: Yes, by codebase mapping agents
• Committed: Yes

.idea/:

• Purpose: JetBrains IDE project settings
• Generated: Yes, by GoLand/IntelliJ
• Committed: Partially (has its own .gitignore)

Build Artifacts and Outputs

Go Binary:

• Built by: go build -o server ./cmd/diunwebhook/main.go (in Docker) or go run ./cmd/diunwebhook/ (local)
• Output: ./server binary (in Docker build stage)

Frontend Bundle:

• Built by: bun run build (runs tsc -b && vite build)
• Output: frontend/dist/ directory
• Consumed by: Go file server at / route, copied into Docker image at /app/frontend/dist/

Docker Image:

• Built by: docker build -t diun-webhook-dashboard .
• Multi-stage: frontend build (Bun) -> Go build (golang) -> runtime (Alpine)
• Contains: Go binary at /app/server, frontend at /app/frontend/dist/

SQLite Database:

• Created at runtime by InitDB()
• Default path: ./diun.db (overridable via DB_PATH env var)
• Docker: /data/diun.db with volume mount

---

Structure analysis: 2026-03-23