4.9 KiB
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.