docs: initial project architecture and specification

docs/09-coding-standards.md

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