docs: initial project architecture and specification
This commit is contained in:
@@ -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.
|
||||
+124
@@ -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.
|
||||
Reference in New Issue
Block a user