docs: replace template README with project documentation
This commit is contained in:
parent
b024bcf2da
commit
8550d90a8f
1 changed files with 63 additions and 67 deletions
136
README.md
136
README.md
|
|
@ -1,81 +1,77 @@
|
|||
# Payload Blank Template
|
||||
# Polaris Task Force
|
||||
|
||||
This template comes configured with the bare minimum to get started on anything you need.
|
||||
Web operations and administration hub for the Arma 3 unit Polaris Task Force. Dark-themed dashboard built with Next.js, Payload CMS, and PostgreSQL.
|
||||
|
||||
## Tech stack
|
||||
|
||||
- **Framework**: Next.js 16 (App Router, webpack)
|
||||
- **CMS / Admin**: Payload CMS 3.79.1 (`@payloadcms/db-postgres` + Drizzle)
|
||||
- **Database**: PostgreSQL
|
||||
- **Styling**: Tailwind CSS v4 (CSS-based, no config file) + shadcn/ui (New York style)
|
||||
- **Package manager**: Bun (`bun.lock`, `bunfig.toml`). The package.json scripts use cross-env and reference pnpm — run everything via `bun run`.
|
||||
|
||||
## Features
|
||||
|
||||
- Unit roster with org chart, ranks, assignments, and qualifications
|
||||
- Missions, campaigns, and factions with intel gating by assignment
|
||||
- Logistics: structures with storage grids and whitelist rules, resources, vehicles, shipments with distance and fuel tracking, automated game tick
|
||||
- Banking system: personal and treasury/faction accounts with full transaction ledger
|
||||
- Trading marketplace with NPC vendors, haggling negotiations, patience meters, and buyer-to-seller offers
|
||||
- Player lockers with loadouts, equipment, and wardrobe
|
||||
- Profiles with rank progression, XP, awards, and qualifications
|
||||
- In-app notification inbox (market offers, deal outcomes)
|
||||
- Real-time event log tied to structures and game entities, SSE updates from game ticks
|
||||
- Narrative event flowchart editor (React Flow) for GMs
|
||||
- Full Payload admin panel for content and configuration management
|
||||
|
||||
## Quickstart
|
||||
|
||||
This template can be deployed directly from our Cloud hosting and it will setup MongoDB and cloud S3 object storage for
|
||||
media.
|
||||
1. `bun install`
|
||||
2. `cp .env.example .env`
|
||||
3. **Edit `.env`**: the `DATABASE_URI` line in `.env.example` is outdated (MongoDB). Replace it with a PostgreSQL connection string:
|
||||
```
|
||||
DATABASE_URI=postgres://user:password@localhost:5432/your_database
|
||||
```
|
||||
Set `PAYLOAD_SECRET`, `APP_URL` (default `http://localhost:3000`), and `GAME_TICK_NOTIFY_SECRET`.
|
||||
4. `bun run dev` — starts the dev server at `http://localhost:3000`.
|
||||
- Use `bun run devsafe` to wipe the `.next` cache before starting.
|
||||
|
||||
## Quick Start - local setup
|
||||
Dev credentials: `dev` / `Test123` (if seed data has been applied).
|
||||
|
||||
To spin up this template locally, follow these steps:
|
||||
## Commands
|
||||
|
||||
### Clone
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `bun run dev` | Dev server (webpack, localhost:3000) |
|
||||
| `bun run devsafe` | Clear `.next` cache then start dev |
|
||||
| `bun run devturbo` | Dev server with Turbopack |
|
||||
| `bun run build` | Production build (webpack, increases memory limit) |
|
||||
| `bun run start` | Run the production build |
|
||||
| `bun run staging` | Start with `NODE_ENV=test` |
|
||||
| `bun run test` | Run integration tests then E2E tests |
|
||||
| `bun run test:int` | Vitest integration tests (requires live PostgreSQL) |
|
||||
| `bun run test:e2e` | Playwright E2E tests (auto-starts dev server) |
|
||||
| `bun run db` | Drizzle-kit wrapper (e.g. `bun run db migrate`) |
|
||||
| `bun run generate:types` | Regenerate `payload-types.ts` |
|
||||
| `bun run generate:importmap` | Regenerate admin import map |
|
||||
| `bun run payload <bin>` | Run Payload binaries |
|
||||
| `bun run payload game-tick` | Process shipment arrivals and fuel consumption |
|
||||
| `bun run payload market-tick` | Expire listings and refresh NPC vendor stock |
|
||||
| `bun run deploy` | Bump patch version, build, and deploy |
|
||||
|
||||
After you click the `Deploy` button above, you'll want to have standalone copy of this repo on your machine. If you've
|
||||
already cloned this repo, skip to [Development](#development).
|
||||
Note: `game-tick` and `market-tick` are Payload bins registered in `payload.config.ts`, not npm scripts. Run via `bun run payload`.
|
||||
|
||||
### Development
|
||||
## Project structure
|
||||
|
||||
1. First [clone the repo](#clone) if you have not done so already
|
||||
2. `cd my-project && cp .env.example .env` to copy the example environment variables. You'll need to add the
|
||||
`MONGODB_URI` from your Cloud project to your `.env` if you want to use S3 storage and the MongoDB database that was
|
||||
created for you.
|
||||
- `src/app/(frontend)/` — public-facing app pages (dashboard, logistics, banking, market)
|
||||
- `src/app/(payload)/` — Payload admin panel and API routes
|
||||
- `src/collections/` — Payload collections organized by domain (users, logistics, banking, market, game, etc.)
|
||||
- `src/lib/` — shared utilities (storage rules, banking, shipping, market logic, realtime bus)
|
||||
- `src/components/frontend/` — app UI components
|
||||
- `src/components/ui/` — shadcn/ui primitives
|
||||
- `src/tools/seed/` — seed scripts for initial data
|
||||
- `src/scripts/` — game tick and utility scripts
|
||||
- `tests/int/` — Vitest integration tests
|
||||
- `tests/e2e/` — Playwright E2E tests
|
||||
|
||||
3. `pnpm install && pnpm dev` to install dependencies and start the dev server
|
||||
4. open `http://localhost:3000` to open the app in your browser
|
||||
|
||||
That's it! Changes made in `./src` will be reflected in your app. Follow the on-screen instructions to login and create
|
||||
your first admin user. Then check out [Production](#production) once you're ready to build and serve your app,
|
||||
and [Deployment](#deployment) when you're ready to go live.
|
||||
|
||||
#### Docker (Optional)
|
||||
|
||||
If you prefer to use Docker for local development instead of a local MongoDB instance, the provided docker-compose.yml
|
||||
file can be used.
|
||||
|
||||
To do so, follow these steps:
|
||||
|
||||
- Modify the `MONGODB_URI` in your `.env` file to `mongodb://127.0.0.1/<dbname>`
|
||||
- Modify the `docker-compose.yml` file's `MONGODB_URI` to match the above `<dbname>`
|
||||
- Run `docker-compose up` to start the database, optionally pass `-d` to run in the background.
|
||||
|
||||
## How it works
|
||||
|
||||
The Payload config is tailored specifically to the needs of most websites. It is pre-configured in the following ways:
|
||||
|
||||
### Collections
|
||||
|
||||
See the [Collections](https://payloadcms.com/docs/configuration/collections) docs for details on how to extend this
|
||||
functionality.
|
||||
|
||||
- #### Users (Authentication)
|
||||
|
||||
Users are auth-enabled collections that have access to the admin panel.
|
||||
|
||||
For additional help, see the official [Auth Example](https://github.com/payloadcms/payload/tree/main/examples/auth) or
|
||||
the [Authentication](https://payloadcms.com/docs/authentication/overview#authentication-overview) docs.
|
||||
|
||||
- #### Media
|
||||
|
||||
This is the uploads enabled collection. It features pre-configured sizes, focal point and manual resizing to help you
|
||||
manage your pictures.
|
||||
|
||||
### Docker
|
||||
|
||||
Alternatively, you can use [Docker](https://www.docker.com) to spin up this template locally. To do so, follow these
|
||||
steps:
|
||||
|
||||
1. Follow [steps 1 and 2 from above](#development), the docker-compose file will automatically use the `.env` file in
|
||||
your project root
|
||||
1. Next run `docker-compose up`
|
||||
1. Follow [steps 4 and 5 from above](#development) to login and create your first admin user
|
||||
|
||||
That's it! The Docker instance will help you get up and running quickly while also standardizing the development
|
||||
environment across your teams.
|
||||
|
||||
## Questions
|
||||
|
||||
If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/payload) or start
|
||||
a [GitHub discussion](https://github.com/payloadcms/payload/discussions).
|
||||
For full development notes (auth flow, access control, storage rules, event system, gotchas), see `AGENTS.md`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue