Markdown Converter
Agent skill for markdown-converter
Key context (big picture)
Sign in to like and favorite skills
This repository implements a URL shortener with a Go backend and a React (Vite + TypeScript) frontend. The goal of this file is to give focused, actionable guidance to automated coding agents so they can be immediately productive.
Key context (big picture)
server/cmd/main.go.landing/src/routes/index.tsx and root layout landing/src/routes/__root.tsx./api/links -> repository inserts into MongoDB. Redirect flow: GET /{code} -> handler finds link by short_code and issues redirect; click count updated asynchronously via IncrementClicks.Primary developer workflows (what to run)
docker-compose up -d (file at repo root).server && go run cmd/main.gocd server && go build -o link-shortener cmd/main.golanding && pnpm install (once)landing && pnpm dev (starts Vite on 3000).\start.ps1 from repo root will attempt to start backend and frontend.Project-specific patterns & conventions (what to follow)
internal/service, DB operations in internal/repository, HTTP bindings in internal/handlers.
internal/service/link_service.go contains short-code generation logic and delegates persistence to repository.context.Background() with a short timeout (see internal/handlers/link_handler.go).internal/models/link.go. Indexes are created in internal/database/mongodb.go (short_code unique index).createFormHook and a shared form-context — field components expect useFieldContext() and useStore(field.store, selector) to select meta/errors.
landing/src/components/FormComponents.tsx.['links'] and ['stats'], useMutation to create/delete links; successful mutations call queryClient.invalidateQueries({ queryKey }).Where to make changes (touchpoints)
server/internal/handlers/*.go and implement logic in internal/service/*.go.server/internal/models/link.go and update repository/index creation in server/internal/database/mongodb.go.landing/src/routes/index.tsx, landing/src/components/*, or add new route files under landing/src/routes/ (file-based routing).landing/src/routes/__root.tsx.Common pitfalls & gotchas (explicit)
r.Context() in goroutines that run after the handler returns — request context will be canceled. Use a background context with timeout for background DB updates (clicks). See link_handler.go..env values are loaded in server (we use github.com/joho/godotenv in internal/config/config.go). The repo contains .env.example files; local dev should copy them to .env or rely on environment variables.pnpm install in landing/ and restart Vite.queryKey naming consistent (['links'], ['stats']) so invalidation works properly.Testing & verification hints
/api/links (or UI), then visit http://localhost:8080/{shortCode} and query GET /api/links to confirm clicks increments. If not incrementing, check that asynchronous increment goroutine used a non-cancelable context.mongosh or MongoDB Compass to inspect link_shortener.links collection directly.Files to read first (high signal)
server/cmd/main.go — wiring, CORS, route registrationserver/internal/handlers/link_handler.go — HTTP surfaceserver/internal/service/link_service.go — business logicserver/internal/repository/link_repository.go — DB operationslanding/src/routes/index.tsx — form + queries + UI compositionlanding/src/hooks/form.ts & landing/src/hooks/form-context.ts — form wiringlanding/src/lib/api.ts — client API boundariesEditing guidance for agents
server/cmd/main.go routes.landing/src/routes to follow file-based routing. Use existing UI components under landing/src/components and landing/src/components/ui for consistency.server/internal/models/link.go and update internal/database/mongodb.go index creation if necessary.If you modify runtime wiring (QueryClientProvider, env handling, or server port), update
README.md, docs/DEVELOPMENT.md and start.ps1 to keep quick-start accurate.
If something is ambiguous, ask: provide the file you want changed, the desired behavior, and any example input/expected output.
-- End of file