Jean-Luc Makiola
96c4012e2f
Parallel analysis of tech stack, architecture, structure, conventions, testing patterns, integrations, and concerns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
241 lines
11 KiB
Markdown
241 lines
11 KiB
Markdown
# 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*
|