|
| 1 | +# QuickStack AI Coding Instructions |
| 2 | + |
| 3 | +QuickStack is a self-hosted PaaS built with Next.js 14 (App Router) that manages Kubernetes (k3s) deployments. It uses a custom server (`src/server.ts`) that wraps Next.js to handle WebSockets for terminal streaming. |
| 4 | + |
| 5 | +## Architecture Overview |
| 6 | + |
| 7 | +### Three-Layer Structure |
| 8 | +- **`src/app/`** - Next.js App Router pages and Server Actions (all pages use `'use server'`) |
| 9 | +- **`src/server/`** - Backend services that interact with Kubernetes and database |
| 10 | +- **`src/shared/`** - Shared models, utils, and Zod schemas (used by both frontend and server) |
| 11 | + |
| 12 | +### Key Adapters (`src/server/adapter/`) |
| 13 | +- `kubernetes-api.adapter.ts` - Wraps `@kubernetes/client-node` APIs (`k3s.core`, `k3s.apps`, etc.) |
| 14 | +- `db.client.ts` - Prisma singleton (`dataAccess.client`) |
| 15 | +- `longhorn-api.adapter.ts` - Longhorn storage API |
| 16 | + |
| 17 | +### Service Pattern |
| 18 | +Services are singleton classes exported as default instances: |
| 19 | +```typescript |
| 20 | +class AppService { /* methods */ } |
| 21 | +const appService = new AppService(); |
| 22 | +export default appService; |
| 23 | +``` |
| 24 | + |
| 25 | +## Server Actions Pattern |
| 26 | + |
| 27 | +All server actions use wrappers from `src/server/utils/action-wrapper.utils.ts`: |
| 28 | + |
| 29 | +```typescript |
| 30 | +// For form submissions with Zod validation |
| 31 | +export const saveApp = async (data: AppModel) => |
| 32 | + saveFormAction(data, AppModelSchema, async (validated) => { |
| 33 | + await appService.save(validated); |
| 34 | + return new SuccessActionResult(undefined, 'App saved'); |
| 35 | + }) as Promise<ServerActionResult<any, void>>; |
| 36 | + |
| 37 | +// For simple actions without form validation |
| 38 | +export const deleteApp = async (id: string) => |
| 39 | + simpleAction(async () => { |
| 40 | + await isAuthorizedWriteForApp(id); // Auth check |
| 41 | + await appService.deleteById(id); |
| 42 | + return new SuccessActionResult(undefined, 'App deleted'); |
| 43 | + }); |
| 44 | +``` |
| 45 | + |
| 46 | +## Database & Prisma |
| 47 | + |
| 48 | +- SQLite database at `storage/db/data.db` |
| 49 | +- Schema: `prisma/schema.prisma` |
| 50 | +- Zod schemas auto-generated to `src/shared/model/generated-zod/` |
| 51 | +- After schema changes: `yarn prisma-migrate` (runs `prisma migrate dev` + fixes Zod imports) |
| 52 | +- Use `dataAccess.client` for queries, supports transactions via `$transaction()` |
| 53 | + |
| 54 | +## Kubernetes Naming Conventions |
| 55 | + |
| 56 | +Use `KubeObjectNameUtils` for consistent k8s object names: |
| 57 | +- `toProjectId(name)` → `proj-{name}-{hash}` |
| 58 | +- `toAppId(name)` → `app-{name}-{hash}` |
| 59 | +- `toPvcName(volumeId)` → `pvc-{volumeId}` |
| 60 | +- `toServiceName(appId)` → `svc-{appId}` |
| 61 | + |
| 62 | +## Frontend Patterns |
| 63 | + |
| 64 | +### State Management |
| 65 | +Zustand stores in `src/frontend/states/zustand.states.ts`: |
| 66 | +- `useConfirmDialog` - Promise-based confirmation dialogs |
| 67 | +- `useInputDialog` - Promise-based input dialogs |
| 68 | +- `useBreadcrumbs` - Page breadcrumb navigation |
| 69 | + |
| 70 | +### UI Components |
| 71 | +- shadcn/ui components in `src/components/ui/` |
| 72 | +- Custom components in `src/components/custom/` |
| 73 | +- Forms use `react-hook-form` with Zod resolvers |
| 74 | + |
| 75 | +### Real-time Updates |
| 76 | +- Socket.IO server at `/pod-terminal` namespace for terminal streaming |
| 77 | +- WebSocket server for live pod logs |
| 78 | + |
| 79 | +## Caching |
| 80 | + |
| 81 | +Next.js `unstable_cache` with tag-based invalidation: |
| 82 | +```typescript |
| 83 | +// Reading with cache |
| 84 | +await unstable_cache( |
| 85 | + async () => dataAccess.client.app.findMany({ where: { projectId } }), |
| 86 | + [Tags.apps(projectId)], |
| 87 | + { tags: [Tags.apps(projectId)] } |
| 88 | +)(projectId); |
| 89 | + |
| 90 | +// Invalidating after mutations |
| 91 | +revalidateTag(Tags.apps(projectId)); |
| 92 | +``` |
| 93 | + |
| 94 | +## Testing |
| 95 | + |
| 96 | +- Jest with jsdom environment |
| 97 | +- Tests in `src/__tests__/{frontend,server,shared}/` |
| 98 | +- Path alias `@/` maps to `src/` |
| 99 | +- Run: `yarn test` |
| 100 | + |
| 101 | +## Development Setup |
| 102 | + |
| 103 | +1. Use provided devcontainer (includes Node, Bun, Prisma extension) |
| 104 | +2. Provide k3s credentials in `kube-config.config` at project root |
| 105 | +3. `yarn install` → `yarn dev` for Next.js or `yarn dev-live` for custom server |
| 106 | + |
| 107 | +## Commit Convention |
| 108 | + |
| 109 | +Follow Conventional Commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:` |
0 commit comments