diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index faf956d8f..5195dc346 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -1,3 +1,24 @@
+## Goals and design vision
+
+The goal of stash is to be:
+- an application for organising and viewing adult content - currently this is videos and images, in future this will be extended to include audio and text content
+  - organising includes scraping of metadata from websites and metadata repositories
+- free and open-source
+- portable and offline - can be run on a USB stick without needing to install dependencies (with the exception of ffmpeg)
+- minimal, but highly extensible. The core feature set should be the minimum required to achieve the primary goal, while being extensible enough to extend via plugins
+- easy to learn and use, with minimal technical knowledge required
+
+The core stash system is not intended for:
+- managing downloading of content
+- managing content on external websites
+- publically sharing content
+
+Other requirements:
+- support as many video and image formats as possible
+- interfaces with external systems (for example stash-box) should be made as generic as possible. 
+
+Design considerations:
+- features are easy to add and difficult to remove. Large superfluous features should be scrutinised and avoided where possible (eg DLNA, filename parser). Such features should be considered for third-party plugins instead.
 
 ## Technical Debt
 Please be sure to consider how heavily your contribution impacts the maintainability of the project long term, sometimes less is more.  We don't want to merge collossal pull requests with hundreds of dependencies by a driveby contributor.
diff --git a/internal/api/doc.go b/internal/api/doc.go
new file mode 100644
index 000000000..a0498359a
--- /dev/null
+++ b/internal/api/doc.go
@@ -0,0 +1,2 @@
+// Package api provides the HTTP and Graphql API for the application.
+package api
diff --git a/internal/api/loaders/dataloaders.go b/internal/api/loaders/dataloaders.go
index d1b13db69..fca3e6c18 100644
--- a/internal/api/loaders/dataloaders.go
+++ b/internal/api/loaders/dataloaders.go
@@ -1,3 +1,7 @@
+// Package loaders contains the dataloaders used by the resolver in [api].
+// They are generated with `make generate-dataloaders`.
+// The dataloaders are used to batch requests to the database.
+
 //go:generate go run github.com/vektah/dataloaden SceneLoader int *github.com/stashapp/stash/pkg/models.Scene
 //go:generate go run github.com/vektah/dataloaden GalleryLoader int *github.com/stashapp/stash/pkg/models.Gallery
 //go:generate go run github.com/vektah/dataloaden ImageLoader int *github.com/stashapp/stash/pkg/models.Image
diff --git a/internal/api/server.go b/internal/api/server.go
index 1ddf1baef..b32ee04a0 100644
--- a/internal/api/server.go
+++ b/internal/api/server.go
@@ -75,7 +75,8 @@ func (dir osFS) Open(name string) (fs.File, error) {
 	return os.DirFS(string(dir)).Open(name)
 }
 
-// Called at startup
+// Initialize creates a new [Server] instance.
+// It assumes that the [manager.Manager] instance has been initialised.
 func Initialize() (*Server, error) {
 	mgr := manager.GetInstance()
 	cfg := mgr.Config
@@ -289,6 +290,9 @@ func Initialize() (*Server, error) {
 	return server, nil
 }
 
+// Start starts the server. It listens on the configured address and port.
+// It calls ListenAndServeTLS if TLS is configured, otherwise it calls ListenAndServe.
+// Calls to Start are blocked until the server is shutdown.
 func (s *Server) Start() error {
 	logger.Infof("stash is listening on " + s.Addr)
 	logger.Infof("stash is running at " + s.displayAddress)
@@ -300,6 +304,7 @@ func (s *Server) Start() error {
 	}
 }
 
+// Shutdown gracefully shuts down the server without interrupting any active connections.
 func (s *Server) Shutdown() {
 	err := s.Server.Shutdown(context.TODO())
 	if err != nil {
diff --git a/internal/api/urlbuilders/doc.go b/internal/api/urlbuilders/doc.go
new file mode 100644
index 000000000..636ec50f1
--- /dev/null
+++ b/internal/api/urlbuilders/doc.go
@@ -0,0 +1,2 @@
+// Package urlbuilders provides the builders used to build URLs to pass to clients.
+package urlbuilders
diff --git a/internal/autotag/doc.go b/internal/autotag/doc.go
new file mode 100644
index 000000000..a495949e8
--- /dev/null
+++ b/internal/autotag/doc.go
@@ -0,0 +1,9 @@
+// Package autotag provides the autotagging functionality for the application.
+//
+// The autotag functionality sets media metadata based on the media's path.
+// The functions in this package are in the form of {ObjectType}{TagTypes},
+// where the ObjectType is the single object instance to run on, and TagTypes
+// are the related types.
+// For example, PerformerScenes finds and tags scenes with a provided performer,
+// whereas ScenePerformers tags a single scene with any Performers that match.
+package autotag
diff --git a/internal/build/version.go b/internal/build/version.go
index 84c5f819f..ecccd9703 100644
--- a/internal/build/version.go
+++ b/internal/build/version.go
@@ -1,3 +1,4 @@
+// Package build provides the version information for the application.
 package build
 
 import (
diff --git a/internal/desktop/desktop.go b/internal/desktop/desktop.go
index b5a261bf7..a89a3c962 100644
--- a/internal/desktop/desktop.go
+++ b/internal/desktop/desktop.go
@@ -1,3 +1,4 @@
+// Package desktop provides desktop integration functionality for the application.
 package desktop
 
 import (
diff --git a/internal/dlna/doc.go b/internal/dlna/doc.go
new file mode 100644
index 000000000..b5955c349
--- /dev/null
+++ b/internal/dlna/doc.go
@@ -0,0 +1,3 @@
+// Package dlna provides the DLNA functionality for the application.
+// Much of this code is adapted from https://github.com/anacrolix/dms
+package dlna
diff --git a/internal/identify/identify.go b/internal/identify/identify.go
index 43e1dedf3..5eecd0d99 100644
--- a/internal/identify/identify.go
+++ b/internal/identify/identify.go
@@ -1,3 +1,6 @@
+// Package identify provides the scene identification functionality for the application.
+// The identify functionality uses scene scrapers to identify a given scene and
+// set its metadata based on the scraped data.
 package identify
 
 import (
diff --git a/internal/log/logger.go b/internal/log/logger.go
index 50f5a42b4..5f686d32d 100644
--- a/internal/log/logger.go
+++ b/internal/log/logger.go
@@ -1,3 +1,4 @@
+// Package log provides an implementation of [logger.LoggerImpl], using logrus.
 package log
 
 import (
diff --git a/internal/manager/manager.go b/internal/manager/manager.go
index 7032c3329..397503930 100644
--- a/internal/manager/manager.go
+++ b/internal/manager/manager.go
@@ -1,3 +1,5 @@
+// Package manager provides the core manager of the application.
+// This consolidates all the services and managers into a single struct.
 package manager
 
 import (
diff --git a/internal/static/embed.go b/internal/static/embed.go
index 3c9323a70..38614ae79 100644
--- a/internal/static/embed.go
+++ b/internal/static/embed.go
@@ -1,3 +1,4 @@
+// Package static provides the static files embedded in the application.
 package static
 
 import (
diff --git a/pkg/file/file.go b/pkg/file/file.go
index 72c7f8a1a..407949ba1 100644
--- a/pkg/file/file.go
+++ b/pkg/file/file.go
@@ -1,3 +1,4 @@
+// Package file provides functionality for managing, scanning and cleaning files and folders.
 package file
 
 import (
diff --git a/pkg/fsutil/fs.go b/pkg/fsutil/fs.go
index 0b9fc6416..2b5c37f62 100644
--- a/pkg/fsutil/fs.go
+++ b/pkg/fsutil/fs.go
@@ -1,3 +1,4 @@
+// Package fsutil provides filesystem utility functions for the application.
 package fsutil
 
 import (
diff --git a/pkg/gallery/service.go b/pkg/gallery/service.go
index 6db604fc4..a764e982c 100644
--- a/pkg/gallery/service.go
+++ b/pkg/gallery/service.go
@@ -1,3 +1,5 @@
+// Package gallery provides application logic for managing galleries.
+// This functionality is exposed via the [Service] type.
 package gallery
 
 import (
diff --git a/pkg/group/doc.go b/pkg/group/doc.go
new file mode 100644
index 000000000..754f043fc
--- /dev/null
+++ b/pkg/group/doc.go
@@ -0,0 +1,2 @@
+// Package group provides the application logic for groups.
+package group
diff --git a/pkg/image/service.go b/pkg/image/service.go
index 55dc7686d..cb0b24ec3 100644
--- a/pkg/image/service.go
+++ b/pkg/image/service.go
@@ -1,3 +1,5 @@
+// Package image provides the application logic for images.
+// The functionality is exposed via the [Service] type.
 package image
 
 import (
diff --git a/pkg/javascript/vm.go b/pkg/javascript/vm.go
index 556edb1d6..2ac4b59dc 100644
--- a/pkg/javascript/vm.go
+++ b/pkg/javascript/vm.go
@@ -1,8 +1,8 @@
+// Package javascript provides the javascript runtime for the application.
 package javascript
 
 import (
 	"fmt"
-	"net/http"
 	"os"
 	"reflect"
 
@@ -10,12 +10,9 @@ import (
 	"github.com/stashapp/stash/pkg/logger"
 )
 
+// VM is a wrapper around goja.Runtime.
 type VM struct {
 	*goja.Runtime
-
-	Progress      chan float64
-	SessionCookie *http.Cookie
-	GQLHandler    http.Handler
 }
 
 // optionalFieldNameMapper wraps a goja.FieldNameMapper and returns the field name if the wrapped mapper returns an empty string.
diff --git a/pkg/job/job.go b/pkg/job/job.go
index fa1ef3c91..48b5e7b13 100644
--- a/pkg/job/job.go
+++ b/pkg/job/job.go
@@ -1,3 +1,4 @@
+// Package job provides the job execution and management functionality for the application.
 package job
 
 import (
diff --git a/pkg/match/path.go b/pkg/match/path.go
index 171d9a530..1755e7012 100644
--- a/pkg/match/path.go
+++ b/pkg/match/path.go
@@ -1,3 +1,4 @@
+// Package match provides functions for matching paths to models.
 package match
 
 import (
diff --git a/pkg/models/doc.go b/pkg/models/doc.go
new file mode 100644
index 000000000..515f5775f
--- /dev/null
+++ b/pkg/models/doc.go
@@ -0,0 +1,2 @@
+// Package models provides application models that are used throughout the application.
+package models
diff --git a/pkg/models/json/json_time.go b/pkg/models/json/json_time.go
index 134bc69c6..20ef9b442 100644
--- a/pkg/models/json/json_time.go
+++ b/pkg/models/json/json_time.go
@@ -1,3 +1,4 @@
+// Package json provides generic JSON types.
 package json
 
 import (
diff --git a/pkg/models/jsonschema/doc.go b/pkg/models/jsonschema/doc.go
new file mode 100644
index 000000000..d19852ac1
--- /dev/null
+++ b/pkg/models/jsonschema/doc.go
@@ -0,0 +1,2 @@
+// Package jsonschema provides the JSON schema models used for importing and exporting data.
+package jsonschema
diff --git a/pkg/models/mocks/database.go b/pkg/models/mocks/database.go
index 189299210..ec4177b30 100644
--- a/pkg/models/mocks/database.go
+++ b/pkg/models/mocks/database.go
@@ -1,3 +1,4 @@
+// Package mocks provides mocks for various interfaces in [models].
 package mocks
 
 import (
diff --git a/pkg/models/paths/paths.go b/pkg/models/paths/paths.go
index ed35bca56..da72111cf 100644
--- a/pkg/models/paths/paths.go
+++ b/pkg/models/paths/paths.go
@@ -1,3 +1,4 @@
+// Package paths provides functions to return paths to various resources.
 package paths
 
 import (
diff --git a/pkg/performer/doc.go b/pkg/performer/doc.go
new file mode 100644
index 000000000..67a36f88c
--- /dev/null
+++ b/pkg/performer/doc.go
@@ -0,0 +1,2 @@
+// Package performer provides the application logic for performer functionality.
+package performer
diff --git a/pkg/pkg/pkg.go b/pkg/pkg/pkg.go
index 7c2e734ef..51c35c3d7 100644
--- a/pkg/pkg/pkg.go
+++ b/pkg/pkg/pkg.go
@@ -1,3 +1,4 @@
+// Package pkg provides interfaces to interact with the package system used for plugins and scrapers.
 package pkg
 
 import (
diff --git a/pkg/python/exec.go b/pkg/python/exec.go
index 68fd18c88..098635294 100644
--- a/pkg/python/exec.go
+++ b/pkg/python/exec.go
@@ -1,3 +1,4 @@
+// Package python provides utilities for working with the python executable.
 package python
 
 import (
diff --git a/pkg/scene/generate/generator.go b/pkg/scene/generate/generator.go
index 70f6857ea..7e5705679 100644
--- a/pkg/scene/generate/generator.go
+++ b/pkg/scene/generate/generator.go
@@ -1,3 +1,4 @@
+// Package generate provides functions to generate media assets from scenes.
 package generate
 
 import (
diff --git a/pkg/scene/service.go b/pkg/scene/service.go
index 05fa9f532..f5a117309 100644
--- a/pkg/scene/service.go
+++ b/pkg/scene/service.go
@@ -1,3 +1,5 @@
+// Package scene provides the application logic for scene functionality.
+// Most functionality is provided by [Service].
 package scene
 
 import (
diff --git a/pkg/scraper/scraper.go b/pkg/scraper/scraper.go
index 1e814bd8a..56c8f0073 100644
--- a/pkg/scraper/scraper.go
+++ b/pkg/scraper/scraper.go
@@ -1,3 +1,5 @@
+// Package scraper provides interfaces to interact with the scraper subsystem.
+// The [Cache] type is the main entry point to the scraper subsystem.
 package scraper
 
 import (
diff --git a/pkg/scraper/stashbox/stash_box.go b/pkg/scraper/stashbox/stash_box.go
index 1432eef17..0b0cf68d6 100644
--- a/pkg/scraper/stashbox/stash_box.go
+++ b/pkg/scraper/stashbox/stash_box.go
@@ -1,3 +1,4 @@
+// Package stashbox provides a client interface to a stash-box server instance.
 package stashbox
 
 import (
diff --git a/pkg/session/session.go b/pkg/session/session.go
index 285c7cc3c..66cb39e09 100644
--- a/pkg/session/session.go
+++ b/pkg/session/session.go
@@ -1,3 +1,4 @@
+// Package session provides session authentication and management for the application.
 package session
 
 import (
diff --git a/pkg/sliceutil/collections.go b/pkg/sliceutil/collections.go
index 81a3deba3..bd4070cdc 100644
--- a/pkg/sliceutil/collections.go
+++ b/pkg/sliceutil/collections.go
@@ -1,3 +1,4 @@
+// Package sliceutil provides utilities for working with slices.
 package sliceutil
 
 // Index returns the first index of the provided value in the provided
diff --git a/pkg/sqlite/doc.go b/pkg/sqlite/doc.go
new file mode 100644
index 000000000..364721896
--- /dev/null
+++ b/pkg/sqlite/doc.go
@@ -0,0 +1,2 @@
+// Package sqlite provides interfaces to interact with the sqlite database.
+package sqlite
diff --git a/pkg/studio/doc.go b/pkg/studio/doc.go
new file mode 100644
index 000000000..72c429c57
--- /dev/null
+++ b/pkg/studio/doc.go
@@ -0,0 +1,2 @@
+// Package studio provides the application logic for studio functionality.
+package studio
diff --git a/pkg/tag/doc.go b/pkg/tag/doc.go
new file mode 100644
index 000000000..604ab88c1
--- /dev/null
+++ b/pkg/tag/doc.go
@@ -0,0 +1,2 @@
+// Package tag provides application logic for tag objects.
+package tag
diff --git a/pkg/txn/transaction.go b/pkg/txn/transaction.go
index 751588eff..b8d0aa830 100644
--- a/pkg/txn/transaction.go
+++ b/pkg/txn/transaction.go
@@ -1,3 +1,4 @@
+// Package txn provides functions for running transactions.
 package txn
 
 import (
diff --git a/pkg/utils/doc.go b/pkg/utils/doc.go
new file mode 100644
index 000000000..2ea42ced3
--- /dev/null
+++ b/pkg/utils/doc.go
@@ -0,0 +1,2 @@
+// Package utils provides various utility functions for the application.
+package utils