Home

Welcome to the capuchin wiki!

📜 Capuchin: A robust Todo application

A feature-rich full-stack todo list application with a Go (Golang) REST API backend and a React/Vite frontend using a professional-grade decoupled architecture.

🚀 Features Implemented

• Backend (Go + Gin): RESTful API with distinct layers (handlers, services, database, middleware) and robust error handling.
• Authentication: Secure Signup, Login, and Logout using short-lived JWT tokens with a database-backed token blacklisting mechanism.
• Database (PostgreSQL): Relational persistence mapped implicitly to user context to enforce cross-tenant data isolation.
• Frontend (React + Vite): Modern reactive UI with custom asynchronous Hooks (useTodos, useAuth) abstracting away native fetch requests.
• Offline-friendly mode: Supports an unauthenticated Guest mode backed tightly by localStorage.
• Containerization: Clean Docker Compose multi-stage orchestrations covering both isolated local development profiles and production scratch-image deployment.

📂 Project Structure

capuchin/
├── backend/
│   ├── cmd/
│   │   ├── server/           # Entry point for the REST server
│   │   ├── migrate/          # Standalone binary runner for schema definitions
│   │   └── seed/             # Dev DB seed runner
│   ├── internal/
│   │   ├── config/           # Environment & Config map parsing
│   │   ├── database/         # PostgreSQL driver configuration & pooling limits 
│   │   ├── handlers/         # HTTP Route logic & payload validation
│   │   ├── middleware/       # Identity resolution & security guards
│   │   ├── models/           # Data structures
│   │   ├── routes/           # Mux mappings setup
│   │   └── services/         # Identity and persistence core logic workflows
│   ├── Dockerfile            # Multi-stage Backend Container 
│   ├── air.toml              # Hot Reload configs
│   ├── go.mod                # Go Dependencies
│   └── test.sh               # Integration / E2E endpoint bash test harness
├── frontend/
│   ├── src/
│   │   ├── components/       # Presentational layout components
│   │   ├── hooks/            # Primary React state workflows (`useAuth`, `useTodos`) 
│   │   ├── lib/              # Core native-fetch wrapper API logic
│   │   ├── pages/            # Page-level route views
│   │   ├── types/            # TypeScript definitions
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── Dockerfile            # Nginx + React Multi-stage Frontend Container
│   ├── vite.config.ts        # Vite bundling settings
│   └── package.json
├── compose.yml               # Lean Production Orchestration
├── compose-dev.yml           # Dev Mode (Air/Vite) overrides
└── Makefile                  # Command shortcuts

🧠 Documentation

For an in-depth dive into the structure and patterns, please refer to our dedicated guides:

• Running The Project - How to run native vs Docker bounds.
• Architecture - System design and logic separation map.
• Backend Best Practices - Go coding conventions and clean boundaries.
• Frontend Best Practices - React hook rules and application layout instructions.
• API Reference - Complete endpoints behavior map.
• Database Guide - Isolation patterns and migrations guide.
• Production Guidelines - Nginx proxying, scratch image builds, and logging strategy.