Developer · Project structure
Developer Docs

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 scripts

apps/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, symbols

The 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 driver

packages/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 from

Everything 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.

Continue to the parametric system