Enterprise Web Template

Full-stack Next.js + FastAPI + PostgreSQL template based on a modular monolith in a hybrid monorepo.

Stack

Layer	Technology
Frontend	Next.js, TypeScript
Backend	Python, FastAPI, Pydantic
Database	PostgreSQL, SQLAlchemy async, Alembic
Cache / queue	Redis, Celery
Container	Docker Compose

Repository structure

apps/web          Next.js frontend
apps/api          FastAPI backend
apps/worker       Celery worker
packages/         Shared UI + generated API client
infrastructure/   Docker, database SQL baseline, nginx, monitoring
docs/             Architecture, modules, security, ADR

---

Prerequisites

Component	Version / notes
Python	3.11+ (managed with uv)
Node.js	20+ with pnpm
PostgreSQL	15+ (port 5432)
Redis	7.x (port 6379) — access cache + Celery broker
Make	Optional; equivalent commands can be run manually
Docker Compose	Recommended for Postgres + Redis

Install tooling if needed:

# Python package manager
pip install uv

# Node package manager
npm install -g pnpm

---

Installation

1. Clone the repository

git clone https://github.com/wendibarmara/enterprise_web_template.git
cd enterprise_web_template

2. Create environment file

cp .env.example .env

Key defaults for local development:

Variable	Recommended value
APP_ENV	development
DEBUG	true
AUTH_MODE	local
AUTH_PERSISTENCE	database
EXTERNAL_UM_BASE_URL	(leave empty — company UM deferred)
ACCESS_CACHE_BACKEND	redis
CORS_ORIGINS	http://localhost:3000

3. Install dependencies

make setup

Or manually:

python -m uv sync --extra dev
pnpm install

4. Start infrastructure

docker compose up -d postgres redis

Verify ports:

• PostgreSQL → localhost:5432
• Redis → localhost:6379

5. Initialize the database

Compose mounts SQL under infrastructure/database/ on first Postgres start:

• 01_schema.sql — auth, dynamic ACL, customers
• 02_seed_dummy.sql — development seed data

If you use an existing Postgres instance, apply the scripts manually (see infrastructure/database/README.md), then:

make migrate-stamp

For later schema changes, use Alembic:

make migrate

6. Health check

make doctor

---

Operation (development)

Open separate terminals:

make api      # http://localhost:8000
make web      # http://localhost:3000
make worker   # optional — async jobs (e.g. export)

URL	Purpose
http://localhost:3000	Web UI
http://localhost:8000/health/live	API liveness
http://localhost:8000/docs	OpenAPI (disabled in production by default)

Demo accounts

Password for all seeded users: ChangeMe123!

Username	Typical role
superadmin	Full access
orgadmin	Organization admin
manager	Operational + edit
operator	Limited operational
viewer	Read-only
auditor	Audit / read

Demo seed is for development only. In production set AUTH_SEED_DEMO_USERS=false.

Daily workflows

Task	Command
Run API	make api
Run frontend	make web
Run Celery worker	make worker
Regenerate API client after endpoint changes	make api-client
Run tests	make test
Lint / typecheck	make lint / make typecheck
Apply migrations	make migrate
Repository health	make doctor

Example module

• UI: /master-data/customers
• API: /api/v1/customers
• Permissions: CUSTOMERS:view|create|edit|delete|export

Session cookie name: webapp_session (HttpOnly). Menu and action buttons follow /api/v1/me/menu and /api/v1/me/access; the backend remains the final authority (default DENY).

---

Production operation

1. Copy .env.production.example → .env on the server and fill secrets.
2. Ensure PostgreSQL and Redis are available; run make migrate.
3. Keep AUTH_MODE=local and EXTERNAL_UM_BASE_URL= empty until company User Management is ready.
4. Serve the API behind HTTPS; set explicit CORS_ORIGINS and TRUSTED_HOSTS.
5. Startup validation will refuse unsafe production settings (weak SECRET_KEY, DEBUG=true, demo seed, etc.).

Details: docs/security/baseline.md.

---

Useful Make targets

Command	Description
make setup	Install Python + Node dependencies
make api / make web	Run API / frontend
make api-client	Export OpenAPI + generate @repo/api-client
make migrate / make migrate-stamp	Alembic upgrade / stamp baseline
make worker	Celery worker (default, reports queues)
make test	Unit / API tests
make lint / make typecheck	Quality gates
make doctor	Repository health check
docker compose up	Full stack containers

---

Documentation

Document	Contents
docs/PETUNJUK_PEMAKAIAN.md	Usage guide (Indonesian)
docs/PETUNJUK_MODUL_BARU.md	How to add a new module (Indonesian)
docs/architecture/galeri-arsitektur.md	Architecture images (PNG)
docs/architecture/arsitektur-aplikasi.md	Architecture diagrams (Mermaid + images)
docs/security/baseline.md	Production hardening
AGENTS.md / AI_CODING_RULES.md / AI_CODING_COMMANDS.md	AI coding agent guides

---

Current status

• Template complete with production hardening and local auth.
• Default: AUTH_MODE=local.
• Company User Management (EXTERNAL_UM_BASE_URL) is deferred; hybrid adapter is present and can be enabled later with https://... + contract tests.