Merge pull request #7 from sumon-ohid/backend-restucture

Backend restucture

Author: sumon-ohid

CONTRIBUTING.md

@@ -56,6 +56,9 @@ go run .
 ```
 The API server will listen on `http://localhost:8080` by default.
 
+For a quick map of backend files and responsibilities, see
+[`backend/docs/architecture.md`](backend/docs/architecture.md).
+
 ### 3. Run the Frontend
 The frontend is a Next.js single-page application.
 ```bash

Dockerfile

@@ -4,7 +4,7 @@ WORKDIR /src
 COPY backend/go.mod backend/go.sum ./
 RUN go mod download
 COPY backend/ ./
-RUN CGO_ENABLED=0 go build -ldflags "-X main.version=docker" -o better-paas-backend .
+RUN CGO_ENABLED=0 go build -ldflags "-X paas/internal/paas.version=docker" -o better-paas-backend .
 
 # Stage 2: Build the Next.js Frontend
 FROM node:20-alpine AS frontend-builder

README.md

@@ -197,7 +197,7 @@ git tag v1.3.0
 git push origin v1.3.0   # builds and publishes the release
 ```
 
-Each release cross-compiles the Go backend for `linux/amd64`, `linux/arm64`, `darwin/amd64`, and `darwin/arm64`, embeds the version tag via `-ldflags "-X main.version=<tag>"`, and attaches the compiled binaries along with a `SHA256SUMS` verification manifest to the GitHub Release.
+Each release cross-compiles the Go backend for `linux/amd64`, `linux/arm64`, `darwin/amd64`, and `darwin/arm64`, embeds the version tag via `-ldflags "-X paas/internal/paas.version=<tag>"`, and attaches the compiled binaries along with a `SHA256SUMS` verification manifest to the GitHub Release.
 
 ### How the In-App Updater Works
 1.  **Version Checking**: The current running version is baked into the server binary. Updates check the GitHub Releases API for the repository slug defined in `UPDATE_REPO` (resolved from environment, database, or git remote origin).

backend/docs/architecture.md

@@ -0,0 +1,54 @@
+# Backend Architecture
+
+The backend is a Go module. The executable entrypoint lives at `main.go` in
+the backend root, while the main application package lives in `internal/paas`.
+
+## Layout
+
+- `main.go`: binary entrypoint. Keep this thin.
+- `internal/paas/`: API process, domain models, deployment workflows, storage,
+  background jobs, tests, and feature handlers.
+- `internal/catalog/`: curated one-click app template data and template
+  structs. Edit app catalog definitions here.
+- `internal/paas/app.go`: boot sequence for the API process and background workers.
+- `internal/paas/routes.go`: HTTP and WebSocket route registration, grouped by feature area.
+- `internal/paas/http_middleware.go`: auth gate, CORS, and request body protection.
+- `internal/paas/config.go`: environment parsing and process-level runtime configuration.
+- `internal/paas/models.go`: shared domain models passed between handlers, storage, and
+  deployment code.
+- `internal/paas/db.go`: SQLite initialization, migrations, and persistence helpers.
+- `internal/paas/catalog.go`: catalog API handlers, image size fetching, and custom catalog
+  deploy orchestration.
+- `internal/paas/docker.go`, `internal/paas/compose.go`, `internal/paas/caddy.go`, `internal/paas/executor.go`: deployment,
+  container, compose, proxy, local, and SSH execution workflows.
+- Feature files such as `internal/paas/addons.go`, `internal/paas/backup.go`,
+  `internal/paas/cron.go`, `internal/paas/domains.go`,
+  `internal/paas/servers.go`, `internal/paas/terminal.go`, and
+  `internal/paas/analytics*.go` own their API behavior.
+
+## Contributor Guidelines
+
+Prefer small, feature-named files over broad catch-all files. When a file grows
+large, split by responsibility first:
+
+- request handlers
+- storage helpers
+- background jobs
+- provider/client code
+- static or curated data
+
+Keep `main.go` limited to calling `paas.Run()`. This keeps the
+runtime path easy to test and avoids hiding behavior in the command package.
+
+Go packages are directory-scoped, so moving feature files into subdirectories
+also creates new packages. Prefer incremental moves into `internal/<feature>`
+when the code has a clean boundary, as with `internal/catalog`. Avoid moving a
+large file just for tidiness if it would require exporting unrelated globals or
+handler internals.
+
+Run backend checks from this directory:
+
+```bash
+go test ./...
+go run .
+```

backend/go.mod

@@ -1,4 +1,4 @@
-module baas
+module paas
 
 go 1.25.0