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.