refactor: clean up flake.nix and nixos configurations for improved readability and organization

- Reformatted `flake.nix` for better structure and consistency, including adjustments to package lists and added metadata for applications.
- Updated `nixos/gitea-runner.nix` to streamline configuration and improve clarity.
- Refined `nixos/tests.nix` by consolidating service definitions and enhancing test scripts for better maintainability and readability.

flake.nix

@@ -6,12 +6,15 @@
     flake-utils.url = "github:numtide/flake-utils";
   };
 
-  outputs = { self, nixpkgs, flake-utils }:
-    flake-utils.lib.eachDefaultSystem (system:
+  outputs =
+    { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
 
-        pythonEnv = pkgs.python3.withPackages (ps: with ps; [
+        pythonEnv = pkgs.python3.withPackages (
+          ps: with ps; [
             # Core backend dependencies
             fastapi
             uvicorn
@@ -36,7 +39,8 @@
             pytest
             pytest-cov
             pytest-asyncio
-        ]);
+          ]
+        );
       in
       {
         devShells.default = pkgs.mkShell {
@@ -98,6 +102,18 @@
 
         # Apps - Scripts that can be run with `nix run`
         apps = {
+          default = {
+            type = "app";
+            program = "${pkgs.writeShellScript "help" ''
+              echo "Available commands:"
+              echo "  nix run .#lint      - Run linting checks"
+              echo "  nix run .#lint-fix  - Auto-fix linting issues"
+            ''}";
+            meta = {
+              description = "Show available commands";
+            };
+          };
+
           # Unified linting for all code
           lint = {
             type = "app";
@@ -132,6 +148,9 @@
               echo ""
               echo "✅ All linting checks passed!"
             ''}";
+            meta = {
+              description = "Run linting checks on backend and frontend code";
+            };
           };
 
           # Auto-fix linting issues
@@ -162,29 +181,48 @@
               echo ""
               echo "✅ Auto-fix complete!"
             ''}";
+            meta = {
+              description = "Auto-fix linting issues in backend and frontend code";
+            };
           };
         };
 
         # Package definitions (for production deployment)
-        packages = {
+        packages = rec {
           # Backend package
           backend = pkgs.python3Packages.buildPythonApplication {
             pname = "webref-backend";
             version = "1.0.0";
+            pyproject = true;
             src = ./backend;
+
+            build-system = with pkgs.python3Packages; [
+              setuptools
+            ];
+
             propagatedBuildInputs = with pkgs.python3Packages; [
               fastapi
               uvicorn
               sqlalchemy
               alembic
               pydantic
+              pydantic-settings
+              psycopg2
               python-jose
               passlib
               pillow
               boto3
               httpx
               python-multipart
+              email-validator
+              bcrypt
             ];
+
+            meta = {
+              description = "Reference Board Viewer - Backend API";
+              homepage = "https://github.com/yourusername/webref";
+              license = pkgs.lib.licenses.mit;
+            };
           };
 
           # Frontend package
@@ -200,12 +238,18 @@
               mkdir -p $out
               cp -r build/* $out/
             '';
+            meta = {
+              description = "Reference Board Viewer - Frontend SPA";
+              homepage = "https://github.com/yourusername/webref";
+              license = pkgs.lib.licenses.mit;
             };
           };
 
+          default = backend;
+        };
+
         # NixOS VM tests
         checks = import ./nixos/tests.nix { inherit pkgs; };
       }
     );
 }
-

nixos/gitea-runner.nix

@@ -1,4 +1,4 @@
-{ config, pkgs, lib, ... }:
+{ pkgs, ... }:
 
 {
   # Gitea Actions Runner Configuration
@@ -75,7 +75,7 @@
     extraGroups = [ "docker" ];
   };
 
-  users.groups.gitea-runner = {};
+  users.groups.gitea-runner = { };
 
   # Allow runner to use Nix
   nix.settings = {
@@ -83,7 +83,10 @@
     trusted-users = [ "gitea-runner" ];
 
     # Enable flakes for the runner
-    experimental-features = [ "nix-command" "flakes" ];
+    experimental-features = [
+      "nix-command"
+      "flakes"
+    ];
 
     # Optimize for CI performance
     max-jobs = "auto";
@@ -109,4 +112,3 @@
     };
   };
 }
-

nixos/tests.nix

@@ -6,15 +6,19 @@
     name = "webref-backend-integration";
 
     nodes = {
-      machine = { config, pkgs, ... }: {
+      machine =
+        { pkgs, ... }:
+        {
           # PostgreSQL service
           services.postgresql = {
             enable = true;
             ensureDatabases = [ "webref" ];
-          ensureUsers = [{
+            ensureUsers = [
+              {
                 name = "webref";
                 ensureDBOwnership = true;
-          }];
+              }
+            ];
             authentication = ''
               local all all trust
               host all all 127.0.0.1/32 trust
@@ -71,15 +75,19 @@
     name = "webref-full-stack";
 
     nodes = {
-      machine = { config, pkgs, ... }: {
+      machine =
+        { pkgs, ... }:
+        {
           # PostgreSQL
           services.postgresql = {
             enable = true;
             ensureDatabases = [ "webref" ];
-          ensureUsers = [{
+            ensureUsers = [
+              {
                 name = "webref";
                 ensureDBOwnership = true;
-          }];
+              }
+            ];
           };
 
           # MinIO
@@ -125,7 +133,9 @@
     name = "webref-performance";
 
     nodes = {
-      machine = { config, pkgs, ... }: {
+      machine =
+        { pkgs, ... }:
+        {
           services.postgresql.enable = true;
           services.minio.enable = true;
 
@@ -148,14 +158,18 @@
     name = "webref-security";
 
     nodes = {
-      machine = { config, pkgs, ... }: {
+      machine =
+        { pkgs, ... }:
+        {
           services.postgresql = {
             enable = true;
             ensureDatabases = [ "webref" ];
-          ensureUsers = [{
+            ensureUsers = [
+              {
                 name = "webref";
                 ensureDBOwnership = true;
-          }];
+              }
+            ];
           };
 
           # Create system user for testing
@@ -163,7 +177,7 @@
             isSystemUser = true;
             group = "webref";
           };
-        users.groups.webref = {};
+          users.groups.webref = { };
 
           environment.systemPackages = with pkgs; [
             python3