docs: initial project architecture and specification

2026-06-05 11:34:46 +00:00
commit d360856585
14 changed files with 1990 additions and 0 deletions
@@ -0,0 +1,96 @@
 START HERE
 This document is the entry point for all development work.
 Before implementing any feature, modifying code, generating files, creating migrations, or refactoring existing functionality, read all project documentation.
 ---
 Documentation Reading Order
 1. 01-project-overview.md
 2. 02-architecture.md
 3. 03-database-design.md
 4. 04-routing.md
 5. 05-ui-pages.md
 6. 06-admin-panel.md
 7. 07-deployment.md
 8. 08-roadmap.md
 9. 09-coding-standards.md
 10. 10-project-structure.md
 11. 11-bootstrap-spec.md
 ---
 Source of Truth
 The documentation folder is the authoritative specification.
 If code conflicts with documentation:
 Documentation wins.
 ---
 Project Goals
 Build a:
 - Personal Website
 - Portfolio
 - Technical Blog
 - Contact Hub
 Using:
 - Go
 - Fiber
 - MariaDB
 - Redis
 - HTMX
 - TinyMCE
 ---
 Development Principles
 - Keep implementation simple.
 - Avoid over-engineering.
 - Prefer maintainability.
 - Prefer readability.
 - Follow documented architecture.
 - Follow documented routing.
 - Follow documented database design.
 ---
 Session Recovery
 If implementation context is lost:
 Stop.
 Re-read all documentation files.
 Continue implementation only after documentation review.
 ---
 Important
 Do not introduce:
 - React
 - Vue
 - Angular
 - Next.js
 - Nuxt.js
 - SPA Architecture
 The project uses:
 Server Side Rendering (SSR)
 with:
 Go Templates + HTMX
@@ -0,0 +1,64 @@
 TukangKetik Personal Website
 Overview
 Website personal yang berfungsi sebagai:
 1. Personal Profile
 2. Portfolio Project
 3. Technical Blog
 4. Contact Hub
 Website dibangun menggunakan stack yang ringan, mudah dipelihara, dan memiliki performa tinggi.
 Objectives
 - Menjadi website utama di tukangketik.id
 - Menampilkan profil dan pengalaman
 - Menampilkan daftar project
 - Menyediakan blog untuk artikel teknis
 - Menyediakan halaman kontak
 - Memiliki admin panel sederhana
 - SEO friendly
 - Mudah dideploy menggunakan Docker
 Technology Stack
 Backend
 - Go 1.26
 - Fiber
 - GORM
 - MariaDB
 Frontend
 - HTML Template
 - HTMX
 - Tailwind CSS
 Infrastructure
 - Docker
 - Nginx
 - Let's Encrypt
 - Gitea
 Non Functional Requirements
 - Fast loading
 - Mobile friendly
 - Responsive
 - Minimal JavaScript
 - Easy maintenance
 - Easy backup
 - Easy deployment
 Future Enhancements
 - RSS Feed
 - Search Engine
 - Comment System
 - Markdown Editor
 - Analytics Dashboard
 - CI/CD Deployment
@@ -0,0 +1,60 @@
 Architecture
 High Level Architecture
 Internet
 |
 v
 Nginx
 |
 v
 Go Fiber
 |
 +-- MariaDB
 |
 +-- Static Files
 Components
 Nginx
 Responsibilities:
 - SSL Termination
 - Reverse Proxy
 - Static Asset Cache
 Fiber
 Responsibilities:
 - Routing
 - Authentication
 - Business Logic
 - Template Rendering
 MariaDB
 Responsibilities:
 - User Data
 - Blog Posts
 - Projects
 - Contact Messages
 HTMX
 Responsibilities:
 - Partial Page Updates
 - Dynamic Admin UI
 Rendering Strategy
 Server Side Rendering (SSR)
 HTML generated by Go templates.
 HTMX used only where interaction is required.
 No SPA architecture tapi bisa seperti tampilan SPA
@@ -0,0 +1,188 @@
 Database Design
 Database
 Name:
 tukangketik
 ---
 users
 Administrator website.
 Columns
 Column| Type
 id| bigint
 name| varchar(255)
 email| varchar(255)
 password| varchar(255)
 role| varchar(50)
 created_at| datetime
 updated_at| datetime
 Notes
 Initial version supports single administrator.
 Future version may support multiple users.
 ---
 posts
 Blog articles.
 Columns
 Column| Type
 id| bigint
 title| varchar(255)
 slug| varchar(255)
 excerpt| text
 content| longtext
 featured_image| varchar(255)
 meta_title| varchar(255)
 meta_description| text
 meta_keywords| text
 status| varchar(50)
 published_at| datetime
 created_at| datetime
 updated_at| datetime
 deleted_at| datetime
 Status
 - draft
 - published
 ---
 categories
 Blog categories.
 Columns
 Column| Type
 id| bigint
 name| varchar(100)
 slug| varchar(100)
 created_at| datetime
 updated_at| datetime
 deleted_at| datetime
 ---
 post_categories
 Many-to-many relationship.
 Columns
 Column| Type
 post_id| bigint
 category_id| bigint
 ---
 tags
 Blog tags.
 Columns
 Column| Type
 id| bigint
 name| varchar(100)
 slug| varchar(100)
 created_at| datetime
 updated_at| datetime
 deleted_at| datetime
 ---
 post_tags
 Many-to-many relationship.
 Columns
 Column| Type
 post_id| bigint
 tag_id| bigint
 ---
 projects
 Portfolio projects.
 Columns
 Column| Type
 id| bigint
 title| varchar(255)
 slug| varchar(255)
 description| text
 github_url| varchar(255)
 project_url| varchar(255)
 image| varchar(255)
 tech_stack| text
 featured| boolean
 created_at| datetime
 updated_at| datetime
 deleted_at| datetime
 ---
 contacts
 Messages from contact form.
 Columns
 Column| Type
 id| bigint
 name| varchar(255)
 email| varchar(255)
 subject| varchar(255)
 message| text
 created_at| datetime
 ---
 settings
 Website configuration.
 Columns
 Column| Type
 id| bigint
 key| varchar(255)
 value| text
 created_at| datetime
 updated_at| datetime
 Example Keys
 site_title
 site_description
 site_keywords
 about_content
 contact_email
 contact_phone
 github_url
 linkedin_url
 google_analytics_id
@@ -0,0 +1,101 @@
 Routing Design
 Public Routes
 Home
 GET /
 About
 GET /about
 Projects
 GET /projects
 Project Detail
 GET /projects/:slug
 Blog
 GET /blog
 Blog Detail
 GET /blog/:slug
 Contact
 GET /contact
 POST /contact
 ---
 Authentication
 GET /admin/login
 POST /admin/login
 POST /admin/logout
 ---
 Dashboard
 GET /admin
 ---
 Posts
 GET /admin/posts
 GET /admin/posts/create
 POST /admin/posts
 GET /admin/posts/:id/edit
 PUT /admin/posts/:id
 DELETE /admin/posts/:id
 ---
 Projects
 GET /admin/projects
 GET /admin/projects/create
 POST /admin/projects
 GET /admin/projects/:id/edit
 PUT /admin/projects/:id
 DELETE /admin/projects/:id
 ---
 Categories
 GET /admin/categories
 POST /admin/categories
 PUT /admin/categories/:id
 DELETE /admin/categories/:id
 ---
 Settings
 GET /admin/settings
 PUT /admin/settings
@@ -0,0 +1,82 @@
 UI Structure
 Public Website
 Home
 Sections:
 - Hero
 - About Summary
 - Featured Projects
 - Latest Posts
 - Contact CTA
 ---
 About
 Sections:
 - Profile
 - Skills
 - Experience
 - Certifications
 ---
 Projects
 Cards containing:
 - Image
 - Title
 - Description
 - Tech Stack
 - Links
 ---
 Blog
 Listing page:
 - Featured Image
 - Title
 - Excerpt
 - Published Date
 ---
 Blog Detail
 - Title
 - Metadata
 - Featured Image
 - Content
 ---
 Contact
 Fields:
 - Name
 - Email
 - Subject
 - Message
 ---
 Admin Dashboard
 Widgets:
 - Total Posts
 - Total Projects
 - Total Contacts
 Recent Activities:
 - Latest Posts
 - Latest Messages
@@ -0,0 +1,127 @@
 Admin Panel Design
 Authentication
 Single administrator login.
 Authentication method:
 - Session Based Authentication
 - Redis Session Storage
 - Secure Cookie
 - HTTP Only Cookie
 - CSRF Protection
 ---
 Dashboard
 Widgets:
 - Total Posts
 - Total Projects
 - Total Contacts
 Recent Activities:
 - Latest Posts
 - Latest Contact Messages
 ---
 Posts Management
 Features:
 - Create Post
 - Edit Post
 - Delete Post
 - Restore Post
 - Publish Post
 - Draft Post
 Fields:
 - Title
 - Slug
 - Excerpt
 - Content
 - Featured Image
 - Categories
 - Tags
 - Meta Title
 - Meta Description
 - Meta Keywords
 - Status
 Editor:
 - TinyMCE WYSIWYG Editor
 ---
 Projects Management
 Features:
 - Create Project
 - Edit Project
 - Delete Project
 - Restore Project
 Fields:
 - Title
 - Description
 - GitHub URL
 - Project URL
 - Image
 - Tech Stack
 - Featured
 ---
 Categories Management
 Features:
 - Create Category
 - Edit Category
 - Delete Category
 - Restore Category
 ---
 Tags Management
 Features:
 - Create Tag
 - Edit Tag
 - Delete Tag
 - Restore Tag
 ---
 Contact Management
 Features:
 - View Messages
 - Delete Messages
 ---
 Settings
 Editable:
 - Site Title
 - Site Description
 - Site Keywords
 - About Content
 - Contact Email
 - Contact Phone
 - GitHub URL
 - LinkedIn URL
 - Google Analytics ID
@@ -0,0 +1,70 @@
 Deployment Strategy
 Environment
 Production VPS
 Operating System:
 Ubuntu 24.04
 ---
 Components
 Nginx
 Docker
 MariaDB
 Redis
 Go Fiber Application
 ---
 Container Structure
 tukangketik-web
 |
 +-- Fiber Application
 +-- Templates
 +-- Static Assets
 MariaDB
 Redis
 ---
 Reverse Proxy
 Nginx
 tukangketik.id
 |
 +--> Go Fiber Container
 ---
 SSL
 Let's Encrypt
 Automatic Renewal
 ---
 Persistent Storage
 Uploads:
 /opt/data/uploads
 Database:
 MariaDB Docker Volume
 ---
 Backup Targets
 MariaDB
 Uploads
 Gitea Data
@@ -0,0 +1,77 @@
 Development Roadmap
 Phase 1
 Project Setup
 - Initialize Fiber
 - Configure Environment
 - Setup Database
 - Setup GORM
 - Setup Templates
 ---
 Phase 2
 Public Website
 - Home Page
 - About Page
 - Projects Page
 - Blog Listing
 - Blog Detail
 - Contact Form
 ---
 Phase 3
 Authentication
 - Login
 - Logout
 - Session Management
 ---
 Phase 4
 Admin Panel
 - Dashboard
 - Posts CRUD
 - Projects CRUD
 - Categories CRUD
 - Settings CRUD
 ---
 Phase 5
 Media Management
 - Image Upload
 - Featured Images
 ---
 Phase 6
 Production Deployment
 - Docker
 - Nginx
 - SSL
 ---
 Phase 7
 Enhancements
 - Search
 - RSS Feed
 - Sitemap
 - Analytics
 - CI/CD
@@ -0,0 +1,210 @@
 Coding Standards
 Architecture Pattern
 Application uses:
 - Handler Layer
 - Service Layer
 - Repository Layer
 Pattern.
 ---
 Layer Responsibilities
 Handler Layer
 Responsibilities:
 - Receive HTTP Request
 - Validate Input
 - Call Service Layer
 - Render Templates
 - Return Response
 Must NOT:
 - Execute SQL
 - Contain Business Logic
 ---
 Service Layer
 Responsibilities:
 - Business Logic
 - Validation
 - Workflow Processing
 Must NOT:
 - Handle HTTP Context Directly
 - Execute Raw SQL
 ---
 Repository Layer
 Responsibilities:
 - Database Access
 - CRUD Operations
 - Query Handling
 Must NOT:
 - Handle HTTP Requests
 - Render Templates
 - Contain Business Logic
 ---
 Dependency Injection
 Dependencies must be injected.
 Avoid global variables.
 Use constructor-based dependency injection.
 ---
 Configuration
 All configuration must come from Environment Variables.
 Examples:
 DB_HOST
 DB_PORT
 DB_NAME
 DB_USER
 DB_PASSWORD
 REDIS_HOST
 REDIS_PORT
 REDIS_PASSWORD
 SESSION_SECRET
 APP_ENV
 APP_PORT
 ---
 Logging
 Use structured logging.
 Levels:
 - INFO
 - WARN
 - ERROR
 Never use fmt.Println for production logging.
 ---
 Error Handling
 Never expose internal errors to users.
 Log internal errors.
 Return user-friendly messages.
 Create centralized error handling.
 ---
 Security
 Use:
 - CSRF Protection
 - Secure Cookies
 - HTTP Only Cookies
 - SameSite Cookies
 Passwords:
 - bcrypt
 Never store plaintext passwords.
 ---
 Templates
 Use Go HTML Templates.
 Use layout pattern.
 Keep business logic outside templates.
 Templates should only render data.
 ---
 Database
 Use:
 - GORM
 - Migrations
 - Soft Delete
 Avoid raw SQL unless absolutely necessary.
 ---
 Redis
 Use Redis for:
 - Session Storage
 - Rate Limiting
 - Future Cache Layer
 ---
 File Upload
 Never store uploads inside source code repository.
 Production upload path:
 /opt/data/uploads
 Structure:
 uploads/
 ├── posts
 ├── projects
 ├── profile
 └── settings
 Store only relative file paths in database.
 ---
 Testing
 Future implementation:
 - Unit Test
 - Service Test
 - Repository Test
 Target business logic coverage first.
@@ -0,0 +1,535 @@
 Project Structure
 Root Structure
 tukangketik-web
 ├── cmd
 │   └── web
 │       └── main.go
 │
 ├── internal
 │   ├── config
 │   ├── database
 │   ├── handlers
 │   ├── middleware
 │   ├── models
 │   ├── repositories
 │   ├── services
 │   ├── validators
 │   ├── session
 │   ├── logger
 │   └── utils
 │
 ├── web
 │   ├── templates
 │   │   ├── layouts
 │   │   ├── partials
 │   │   ├── public
 │   │   └── admin
 │   │
 │   ├── static
 │   │   ├── css
 │   │   ├── js
 │   │   ├── images
 │   │   └── vendor
 │   │
 │   └── uploads
 │
 ├── migrations
 │
 ├── docs
 │
 ├── tests
 │
 ├── docker
 │
 ├── scripts
 │
 ├── .env
 ├── .env.example
 ├── .gitignore
 ├── Dockerfile
 ├── docker-compose.yml
 ├── Makefile
 ├── README.md
 ├── CLAUDE.md
 └── go.mod
 ---
 cmd
 Contains application entrypoints.
 Example:
 cmd/web/main.go
 Responsibilities:
 - Load configuration
 - Initialize database
 - Initialize Redis
 - Register routes
 - Start HTTP server
 ---
 internal/config
 Configuration management.
 Responsibilities:
 - Environment variables
 - Application settings
 - Runtime configuration
 Examples:
 database.go
 redis.go
 app.go
 ---
 internal/database
 Database initialization.
 Responsibilities:
 - MariaDB connection
 - GORM configuration
 - Database bootstrap
 Examples:
 database.go
 migrations.go
 ---
 internal/models
 Database entities.
 Examples:
 user.go
 post.go
 category.go
 tag.go
 project.go
 contact.go
 setting.go
 ---
 internal/repositories
 Database access layer.
 Responsibilities:
 - CRUD operations
 - Query abstraction
 Examples:
 post_repository.go
 project_repository.go
 user_repository.go
 ---
 internal/services
 Business logic layer.
 Responsibilities:
 - Validation workflow
 - Business rules
 - Application logic
 Examples:
 post_service.go
 project_service.go
 contact_service.go
 auth_service.go
 ---
 internal/handlers
 HTTP layer.
 Responsibilities:
 - Receive requests
 - Call services
 - Render templates
 - Return responses
 Examples:
 home_handler.go
 blog_handler.go
 admin_post_handler.go
 auth_handler.go
 ---
 internal/middleware
 Application middleware.
 Examples:
 auth.go
 csrf.go
 logging.go
 recovery.go
 rate_limit.go
 ---
 internal/session
 Session management.
 Responsibilities:
 - Redis session store
 - Session helpers
 - Authentication session handling
 ---
 internal/validators
 Input validation.
 Responsibilities:
 - Request validation
 - Form validation
 Examples:
 post_validator.go
 contact_validator.go
 ---
 internal/logger
 Application logging.
 Responsibilities:
 - Structured logging
 - Error logging
 ---
 internal/utils
 Shared utilities.
 Examples:
 slug.go
 pagination.go
 upload.go
 response.go
 ---
 web/templates
 HTML templates.
 layouts
 Base templates.
 Examples:
 base.html
 admin.html
 ---
 partials
 Reusable components.
 Examples:
 navbar.html
 footer.html
 sidebar.html
 alerts.html
 ---
 public
 Public pages.
 Examples:
 home.html
 about.html
 blog.html
 blog_detail.html
 projects.html
 contact.html
 ---
 admin
 Admin pages.
 Examples:
 dashboard.html
 posts.html
 post_form.html
 projects.html
 settings.html
 ---
 web/static
 Static assets.
 css
 Custom stylesheets.
 js
 HTMX helpers.
 TinyMCE configuration.
 Custom JavaScript.
 images
 Theme assets.
 vendor
 Third-party frontend libraries.
 Examples:
 TinyMCE
 HTMX
 Alpine.js (future)
 ---
 web/uploads
 Development upload directory.
 Used only for local development.
 Production uploads must NOT be stored here.
 ---
 migrations
 Database migration files.
 Examples:
 001_create_users.sql
 002_create_posts.sql
 003_create_projects.sql
 ---
 tests
 Application tests.
 Examples:
 service tests
 repository tests
 integration tests
 ---
 docker
 Docker-related files.
 Examples:
 Dockerfile
 nginx.conf
 compose overrides
 ---
 scripts
 Utility scripts.
 Examples:
 backup.sh
 restore.sh
 deploy.sh
 ---
 Infrastructure Dependencies
 Application
 |
 +-- MariaDB
 |
 +-- Redis
 |
 +-- Nginx Reverse Proxy
 ---
 Upload Storage Strategy
 Development:
 web/uploads
 Production:
 /opt/data/uploads
 Structure:
 uploads/
 ├── posts
 ├── projects
 ├── profile
 └── settings
 Store file path only in database.
 Never store binary data in database.
 ---
 Session Strategy
 Authentication Type:
 Session Based Authentication
 Session Storage:
 Redis
 No JWT.
 ---
 Rendering Strategy
 Server Side Rendering (SSR)
 Technology:
 - Go Templates
 - HTMX
 - TinyMCE
 No SPA.
 No Vue.js.
 No React.
 No Next.js.
 Minimal JavaScript.
 SEO Friendly.
 ---
 Design Principles
 Keep it simple.
 Avoid over-engineering.
 Prefer readability over cleverness.
 Business logic belongs in services.
 Database access belongs in repositories.
 Handlers remain thin.
 Documentation is the source of truth.
@@ -0,0 +1,253 @@
 Bootstrap Specification
 Purpose
 The goal of bootstrap phase is to establish a stable foundation for future development.
 No business features should be implemented during bootstrap.
 Only infrastructure and application foundation.
 ---
 Bootstrap Deliverables
 The application must provide:
 - Fiber Application
 - Environment Configuration
 - MariaDB Connection
 - Redis Connection
 - Session Management
 - Template Rendering
 - HTMX Support
 - TinyMCE Integration Ready
 - Health Check Endpoint
 - Docker Support
 - Structured Logging
 ---
 Dependencies
 Required packages:
 Fiber
 Fiber Middleware
 GORM
 MariaDB Driver
 Redis Client
 Session Middleware
 Environment Loader
 Structured Logger
 ---
 Environment Variables
 The application must support:
 APP_NAME
 APP_ENV
 APP_PORT
 DB_HOST
 DB_PORT
 DB_NAME
 DB_USER
 DB_PASSWORD
 REDIS_HOST
 REDIS_PORT
 REDIS_PASSWORD
 SESSION_SECRET
 UPLOAD_PATH
 ---
 Database
 Requirements:
 - GORM
 - Auto Migration disabled
 - Migration-based schema management
 - Connection pooling configured
 ---
 Redis
 Requirements:
 - Connection test during startup
 - Used for session storage
 ---
 Session
 Requirements:
 - Redis-backed session storage
 - Secure cookies
 - HTTP Only cookies
 - SameSite cookies
 ---
 Templates
 Requirements:
 - Go HTML Templates
 - Layout support
 - Partial support
 Template structure:
 layouts
 partials
 public
 admin
 ---
 Static Assets
 Serve:
 /css
 /js
 /images
 ---
 Upload Strategy
 Development:
 web/uploads
 Production:
 /opt/data/uploads
 Must be configurable via environment variable.
 ---
 Health Check
 Endpoint:
 GET /health
 Response:
 {
 "status": "ok"
 }
 Checks:
 - Application running
 - Database reachable
 - Redis reachable
 ---
 Base Routes
 Public:
 GET /
 GET /health
 Admin:
 GET /admin/login
 ---
 Home Page
 Temporary placeholder page.
 Display:
 Application Name
 Environment
 Version
 ---
 Logging
 Use structured logging.
 Log:
 - Startup
 - Shutdown
 - Database Connection
 - Redis Connection
 - Errors
 ---
 Docker
 Provide:
 Dockerfile
 docker-compose.yml
 Environment support
 ---
 Success Criteria
 Bootstrap phase is complete when:
 - Application starts successfully
 - Database connection succeeds
 - Redis connection succeeds
 - Session middleware works
 - Templates render correctly
 - Home page loads
 - Health endpoint works
 - Docker container starts successfully
 No blog functionality required.
 No admin functionality required.
 No CRUD functionality required.
@@ -0,0 +1,124 @@
 CLAUDE.md
 Mandatory Instructions
 Before making any code changes, you MUST read and understand the following documents:
 1. docs/01-project-overview.md
 2. docs/02-architecture.md
 3. docs/03-database-design.md
 4. docs/04-routing.md
 5. docs/05-ui-pages.md
 6. docs/06-admin-panel.md
 7. docs/07-deployment.md
 8. docs/08-roadmap.md
 9. docs/09-coding-standards.md
 10. docs/10-project-structure.md
 These documents are the source of truth.
 Do not make assumptions that contradict these documents.
 ---
 Architecture Rules
 Follow:
 Handler
 Service
 Repository
 Pattern.
 Do not place business logic inside handlers.
 Do not execute SQL inside handlers.
 Use dependency injection.
 ---
 Technology Stack
 Backend:
 - Go
 - Fiber
 - GORM
 - MariaDB
 - Redis
 Frontend:
 - Go Templates
 - HTMX
 - TinyMCE
 No SPA.
 No Vue.
 No React.
 No Next.js.
 ---
 Authentication
 Session Based Authentication.
 Redis Session Storage.
 No JWT.
 ---
 Rendering
 Server Side Rendering.
 Use HTMX only where partial updates are required.
 ---
 Uploads
 Never store uploads inside repository.
 Production upload path:
 /opt/data/uploads
 ---
 Database
 Use GORM.
 Use migrations.
 Use soft delete.
 ---
 Coding Style
 Prefer simple solutions.
 Avoid over-engineering.
 Avoid premature abstractions.
 Keep code readable.
 Maintain clear separation of responsibilities.
 ---
 Session Recovery
 If context is lost, re-read all documentation files before continuing implementation.
 Treat documentation as the authoritative project specification.
@@ -0,0 +1,3 @@
 module tukangketik-web
 go 1.26.4