docs: initial project architecture and specification

docs/10-project-structure.md

@@ -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.