🏗️ Touli — Project Structure

Nx monorepo · Next.js web client · Express REST API · shared TypeScript libraries · AWS CDK infrastructure

There is a separate app, apps/mobile (Expo / React Native), documented on its own page — it shares libs/types with this side of the monorepo but has its own screen/routing/lib conventions.

Overview
Architecture flow
Full folder tree
Frontend — apps/client
Backend — apps/server
Shared libraries — libs/
Infrastructure — libs/cdk
Path aliases
Tech stack

Overview

Area	Path	What it is
🌐 Frontend	`apps/client`	Next.js 16 App Router — SSR/SSG public site + admin dashboard
🖥️ Backend	`apps/server`	Express 5 REST API + PostgreSQL (Sequelize)
📱 Mobile	`apps/mobile`	Expo / React Native app — see its own doc
📦 `libs/types`	shared	TypeScript interfaces, enums, DTOs, API path constants — imported by client, server, and mobile
🎨 `libs/ui`	client-only	Ant Design–based component library (atoms → molecules → organisms)
🗄️ `libs/models`	server-only	Sequelize database models
🔍 `libs/seo`	client-only	Structured-data (JSON-LD) schema builders + metadata helpers
☁️ `libs/cdk`	infra	AWS CDK stacks — VPC, ECS, RDS, ECR, pipelines, WAF, CloudWatch

Architecture flow

mermaid

flowchart LR
    U["🧑 Browser"] --> C["apps/client\nNext.js · SSR/SSG · Zustand"]
    C --> S["apps/server\nExpress · JWT · REST API"]
    S --> DB[("PostgreSQL\nvia libs/models")]
    S --> AWS["AWS S3 / SES"]
    M["📱 apps/mobile\nExpo"] --> S

    style U fill:#fce7f3,stroke:#db2777
    style C fill:#eff6ff,stroke:#2563eb
    style S fill:#f0fdf4,stroke:#16a34a
    style DB fill:#fef3c7,stroke:#d97706
    style AWS fill:#fce7f3,stroke:#db2777
    style M fill:#eff6ff,stroke:#2563eb

libs/types is imported by both apps/client and apps/server (and apps/mobile) so request/response shapes can never drift between them. libs/cdk provisions the AWS infrastructure both apps deploy onto but is never imported by application code at runtime.

Full folder tree

text

touli/
├── apps/
│   ├── client/                # Next.js 16 web app
│   ├── server/                # Express 5 REST API
│   ├── mobile/                # Expo app — see docs/mobile/project-structure.md
│   ├── client-e2e/            # Playwright E2E (client)
│   └── server-e2e/            # Jest E2E (server API)
├── libs/
│   ├── types/                  # @workspace/types — shared interfaces, enums, DTOs, API constants
│   ├── ui/                     # @workspace/ui — Ant Design component library (client-only)
│   ├── models/                 # @workspace/models — Sequelize models (server-only)
│   ├── seo/                    # @workspace/seo — JSON-LD schema + metadata helpers (client-only)
│   └── cdk/                    # AWS CDK app — infrastructure as code (not an Nx-buildable lib)
├── docs/                       # guides/, mobile/, architecture/
├── tools/scripts/               # Repo automation (e.g. run-mobile-expo.mjs)
├── nx.json · tsconfig.base.json # Nx + path-alias config
└── package.json                 # Workspace root — single yarn install for the whole repo

Frontend — `apps/client`

Next.js 16, App Router, Turbopack.

text

apps/client/src/
├── app/                         # App Router — route groups, layouts, pages
│   ├── layout.tsx                # Root layout — providers, fonts, i18n
│   ├── (auth)/                   # Route group — no navbar/footer
│   │   ├── layout.tsx
│   │   └── login/page.tsx
│   ├── (main)/                   # Route group — Navbar + Footer shell
│   │   └── page.tsx               # Home page
│   └── admin/                     # Admin dashboard (currently a single placeholder route)
│       └── page.tsx
├── components/
│   ├── layouts/                   # navbar.tsx, footer.tsx
│   ├── modals/                    # modalWrapper.tsx (global portal), sampleModal.tsx, common/sortingModal.tsx
│   ├── auth/                      # AuthHydration.tsx
│   └── common/                    # Shared micro-components
├── store/                         # Zustand — one *.store.ts per domain
│   ├── auth/ · user/ · adminUsers/ · filter/ · common/
│   └── app.store.ts
├── services/                      # Axios-based API clients
│   ├── httpClient.service.ts       # Browser-side axios instance
│   ├── httpServer.service.ts       # Server-side axios instance (SSR/route handlers)
│   ├── auth/                       # auth.client.service.ts · auth.proxy.service.ts · auth.service.ts · socialAuth.client.service.ts
│   ├── user/                       # user.client.service.ts · user.server.service.ts
│   └── common/                     # common.server.service.ts · utils.service.ts
├── constants/                     # routes, navbar/footer menu IDs, cookie keys, locale, image paths, regex
├── data/layouts/                   # NAVBAR_MENU_CONFIG, footer link/social configs (consume constants/)
├── hooks/                          # useInfiniteScroll, useIsMobileDevice, useModalScrollLock, usePageFilters, useSectionData, useTableUrlState
├── utils/
│   ├── common/                     # account, date, file-extension, service-error helpers
│   ├── cookies/                    # client + server cookie helpers
│   └── crypto/                     # cookie encryption
├── functions/                      # renderEmptyValue, toQueryString, getDashboardHref, handleDestination, persistClientAuthSession
├── config/                         # axiosInstance.config.ts
├── providers/                      # antdConfigProvider.tsx
├── layouts/                        # authLayout.tsx
├── i18n/                           # request.ts (next-intl)
├── assets/                         # icon.ts, svgIcons.tsx
├── proxy.ts / proxy.server.ts       # Next.js API-route proxying to apps/server
└── styles/globals.css

Backend — `apps/server`

Express 5, layered routes → controllers → services → dao, PostgreSQL via libs/models (Sequelize).

text

apps/server/src/
├── main.ts                       # Entry point
├── servers/http.server.ts         # HTTP server bootstrap
├── routes/                        # auth · users · profile · parentalConsent · challenge · points · utils · routes.ts (aggregator)
├── controllers/                   # One per route file above
├── services/                      # auth · users · profile · parentalConsent · challenge · points · email · utils
├── dao/                           # auth · users · userRole · refreshToken · userConsent · challenge · challengeInterest ·
│                                    challengeSubmission · deedSubmission · giftInterest · pointsWallet · userChallenge · walletTransaction
├── migrations/                    # Umzug migration scripts + migrator.ts CLI
│   └── scripts/                    # e.g. initial-schema, seed-roles, challenges-schema, points-schema, ...
├── templates/                     # Email templates (parental consent, consent response)
├── common/
│   ├── middleware/                  # auth · permission · validation · rateLimit
│   ├── constants/                   # errors · status(HTTP) · environment · points
│   ├── enums/                       # order · sequelizeErrors
│   ├── interfaces/                  # authenticatedRequest/-User · error · status · email
│   ├── responses/                   # success.response.ts
│   ├── handler/                     # cb / cbError response envelope
│   └── types/
├── config/                        # app.config.ts, jwt.config.ts, sql.config.ts
├── loaders/                        # express.loader.ts, sql.loader.ts (DB connection)
├── utils/                         # aws.utils.ts (S3/SES), winston.utils.ts, error.utils.ts, http.utils.ts
└── certificates/                   # RDS TLS CA bundle

Shared libraries — `libs/`

`libs/types` — `@workspace/types/*`

Imported by client, server, and mobile. Organized by kind, then by domain:

text

libs/types/src/
├── interfaces/    auth · user · common · layouts · challenge · points
├── dto/           auth · user · common · utils · onboarding · challenge · points
├── enums/         auth · user · common · challenge · points
├── constants/api/ common · utils · auth · users · challenge · points · api.constants.ts (base paths)
└── responses/     login · logout · register · emailVerification · userStats

`libs/ui` — `@workspace/ui/*` (client-only)

Ant Design–based component library, three atomic tiers, each theme-tokenized under components/tokens/antd/:

Atoms (26): Badge, Breadcrumb, Button, Cascader, Checkbox, Divider, Dropdown, FallbackImage, Icon, IconButton, Input, Message, PopConfirm, Progress, QRCode, Radio, Rate, Select, Skeleton, Spin, Tag, Text, TextArea, TimeStampPicker, Toggle, Tooltip
Molecules (18): Alert, Card, Carousel, Drawer, Empty, Flex, Grid, Menu, Modal, Notification, Pagination, Popover, Result, Segmented, Steps, Tab, Tour, Upload
Organisms (3): Form (+ FormItem, FormList), Sider, Table

Plus hooks/ (useWindowSize), icons/ (shared SVG logos), utils/.

`libs/models` — `@workspace/models` (server-only)

text

libs/models/src/
├── user.model.ts · auth.model.ts · userRole.model.ts · refreshToken.model.ts · userConsent.model.ts
├── challenge.model.ts · challengeCategory.model.ts · challengeTask.model.ts · challengeSubmission.model.ts
├── userChallenge.model.ts · userTaskProgress.model.ts
├── challengeInterest.model.ts · giftInterest.model.ts
├── deedSubmission.model.ts · pointsWallet.model.ts · walletTransaction.model.ts
└── index.ts   # Barrel export

`libs/seo` — `@workspace/seo` (client-only)

JSON-LD structured-data schema builders (article, breadcrumb, faq, organization, website) + metadata generators, consumed by apps/client's page components for SEO.

Infrastructure — `libs/cdk`

A standalone AWS CDK app (not built through Nx's normal app/lib pipeline — it has its own package.json, cdk.json, tsconfig.json) that provisions the environment apps/server and apps/client deploy onto:

text

libs/cdk/
├── bin/                # cdk.ts (app entry), pipeline.ts
├── lib/
│   ├── stacks/           # client · server · server-pipeline · pipeline · network · security ·
│   │                      storage · common-resources · observability · config
│   └── factories/        # app-factory.ts — wires stacks together per environment
├── resources/           # Reusable constructs: acm, cloudwatch, db (RDS), ec2, ecr, ecs,
│                          iam, policies, s3, security-groups, ssm, vpc, waf
├── config/              # demo / dev / staging / prod environment configs (JSON)
└── src/interfaces/       # repo, securityGroups, serverConfig, config interfaces

Deploys: VPC + security groups → RDS (Postgres) → ECR + ECS (server) → ALB + WAF → CloudWatch alarms, with separate CodePipeline stacks for client and server CI/CD.

Path aliases

Defined once in tsconfig.base.json, available to every app/lib in the workspace.

Alias	Resolves to	Used by
`@client/*`	`apps/client/src/*`	Client
`@workspace/server/*`	`apps/server/src/*`	Server
`@workspace/models` / `@workspace/models/*`	`libs/models/src/*`	Server
`@workspace/types/constants/*`	`libs/types/src/constants/*`	Client · Server · Mobile
`@workspace/types/dto/*`	`libs/types/src/dto/*`	Client · Server · Mobile
`@workspace/types/enums/*`	`libs/types/src/enums/*`	Client · Server · Mobile
`@workspace/types/interfaces/*`	`libs/types/src/interfaces/*`	Client · Server · Mobile
`@workspace/types/responses` (`/*`)	`libs/types/src/responses/*`	Client · Server
`@workspace/ui/components/{atoms,molecules,organisms}/*`	`libs/ui/src/components/ui-lib/antd/*`	Client
`@workspace/ui/hooks/` · `@workspace/ui/utils/`	`libs/ui/src/{hooks,utils}/*`	Client
`@workspace/seo` (`/*`)	`libs/seo/src/*`	Client

Mobile (apps/mobile) resolves @workspace/types/* the same way but uses its own @/lib/* / @/features/* aliases for app-local code — see mobile project structure.

Tech stack

Layer	Library	Version
Monorepo	Nx	20.7.1
Language	TypeScript	5.8.3 (client/server)
Frontend framework	Next.js	16.2.4 (Turbopack)
Frontend framework	React	19.1.4
UI library	Ant Design	6.3.7
Styling	Tailwind CSS	4.2.4
Client state	Zustand	5.0.3
i18n	next-intl	4.11.0
HTTP	axios	1.15.2
Backend framework	Express	5.1.0
ORM	Sequelize / sequelize-typescript	6.37.8 / 2.1.6
Database	PostgreSQL (`pg`)	8.13.1
Auth	Passport.js + jsonwebtoken	0.7.0 / 9.0.2
Migrations	Umzug	3.8.3
Logging	Winston	3.17.0
Cloud SDK	@aws-sdk/client-s3, client-ses	3.980.0
Validation	Zod	4.3.5
Rate limiting	express-rate-limit	8.5.2
Infra	AWS CDK	see `libs/cdk/package.json`
Testing	Jest / Playwright / Testing Library	29.7.0 / 1.36.0 / —
Tooling	ESLint + Prettier, Husky, Yarn 1.22.22	—

_{Touli · keep this file (and docs/mobile/project-structure.md) in sync when app/lib structure changes}

🏗️ Touli — Project Structure ​

Contents ​

Overview ​

Architecture flow ​

Full folder tree ​

Frontend — apps/client ​

Backend — apps/server ​

Shared libraries — libs/ ​

libs/types — @workspace/types/* ​

libs/ui — @workspace/ui/* (client-only) ​

libs/models — @workspace/models (server-only) ​

libs/seo — @workspace/seo (client-only) ​

Infrastructure — libs/cdk ​

Path aliases ​

Tech stack ​

🏗️ Touli — Project Structure

Contents

Overview

Architecture flow

Full folder tree

Frontend — `apps/client`

Backend — `apps/server`

Shared libraries — `libs/`

`libs/types` — `@workspace/types/*`

`libs/ui` — `@workspace/ui/*` (client-only)

`libs/models` — `@workspace/models` (server-only)

`libs/seo` — `@workspace/seo` (client-only)

Infrastructure — `libs/cdk`

Path aliases

Tech stack