Developer · Project structure
User Guide
Developer
A map of the repo, annotated
Where everything lives and why. The tree below mirrors the repository as it exists today — use it to find the right file before you open a search panel.
Top level
repository root
.
├── apps/
│ ├── web/ # Next.js 15 (App Router) · React 19 · Tailwind v4 · zustand · r3f
│ └── api/ # Fastify 5 · Prisma (Postgres 16) · jwt · cors · multipart
├── packages/
│ └── shared/ # @pacfully/shared — types, constants, and the template catalog
├── nginx/
│ └── nginx.conf # reverse proxy: / → web, /api → api (prefix stripped), /files → minio
├── docker-compose.yml # web, api, db (postgres:16-alpine), redis, minio, nginx
├── .env.example # every environment variable, with safe dev defaults
├── build-log/ # per-milestone build records (what was made, verification, deviations)
└── package.json # npm workspaces root + orchestration scriptsapps/web
apps/web/src
app/ # routes (App Router)
│ page.tsx # / marketing home
│ mockups/ # /mockups — gallery of all 11 parametric templates
│ dielines/ # /dielines — gallery of the 6 dieline-capable structures
│ editor/ # /editor + /editor/[templateId] — the 3D/dieline workspace
│ pricing/ · tools/ # plan matrix & export gates · utility pages
│ dashboard/ # /dashboard — signed-in workspace (projects from the api)
│ docs/ # /docs — this documentation (user · developer · api)
│ (auth)/login · (auth)/signup
│ globals.css # Tailwind v4 @theme tokens + the glass / text-accent utilities
├── components/
│ ├── glass/ # GlassCard · GlassPanel · GlassButton · GlassInput · GlassBadge · GlassNav
│ ├── editor/ # EditorShell, Toolbar, AssetPanel, Viewport3D, SceneRig,
│ │ # PackagingModel, DielineView, PropertiesPanel, ViewToggle,
│ │ # ExportDialog, fields
│ └── marketing/ # SiteNav, SiteFooter, TemplateGallery, PricingPlans,
│ # DashboardClient, session helpers…
└── lib/
├── models/ # parametric 3D generators — one file per template
├── dieline/ # parametric dieline generators (6 boxes) + svg/dxf/pdf emitters
└── editor/ # zustand store, serialize, materials, capture, symbolsThe three lib/ directories are the engine: models/ builds the folded 3D meshes, dieline/ builds the flat vector blanks, and editor/ holds the single zustand store both read from. The next page walks through that system in detail.
apps/api
apps/api
prisma/
│ schema.prisma # User · Project · ApiKey · Asset (cuid ids, cascade deletes)
│ migrations/ # SQL migrations applied by prisma migrate
└── src/
├── index.ts # entrypoint — builds the app and listens on PORT/HOST
├── app.ts # buildApp(): plugins, routes, and the ApiError normalizer
├── routes/
│ │ health.ts # GET /health
│ │ auth.ts # register · login · me (bcryptjs, 7-day JWT)
│ │ templates.ts # public catalog: list + by-id
│ │ projects.ts # JWT-scoped project CRUD
│ │ assets.ts # multipart image upload + list
│ │ api-keys.ts # developer key issue/list/revoke
│ │ v1.ts # public /v1/templates surface (x-api-key)
│ └── files.ts # dev file server for /files/<name>
├── plugins/
│ │ prisma.ts # app.prisma decorator
│ │ authenticate.ts # app.authenticate JWT preHandler
│ └── storage.ts # app.storage decorator
├── lib/
│ │ errors.ts # sendError() + HTTP reason phrases (ApiError shape)
│ │ serializers.ts # Prisma rows → shared JSON types (ISO dates, no hashes)
│ └── templates.ts # queryTemplates(): category filter + text search
└── storage/
index.ts · local.ts # StorageDriver interface + local-disk dev driverpackages/shared
packages/shared/src
constants.ts # PRODUCT_NAME, API_ROUTES, LIMITS, TEMPLATE_CATEGORIES
catalog.ts # TEMPLATE_CATALOG — the 11 ParametricTemplate definitions
types.ts # User, Project, ApiKey, Asset, ApiError, BoxDimensions,
# EditorState, MaterialId, FinishId, ArtworkPlacement…
index.ts # the public surface both apps import fromEverything in this package is JSON-friendly (dates are ISO strings, no server-only fields), so web components, api serializers, and external scripts can all consume the same shapes. Changes here are additive by convention — see Contributing.