# Falah Solutions Uganda

A responsive Next.js App Router website with a reviewed ten-project portfolio, locally hosted fonts, custom product concept artwork, service information, project planning guidance, and a database-backed enquiry form.

## Enquiries and email delivery

All project enquiries target **falahsolutionsuganda@gmail.com**. Valid enquiries and optional terms-of-reference documents are saved in PostgreSQL before an email is attempted. The API does not expose a public endpoint for retrieving enquiries or attachments.

### Default email relay

With no mail credentials configured, the server submits enquiries through FormSubmit. **The first submission may trigger a one-time activation email to falahsolutionsuganda@gmail.com. The inbox owner must follow that activation link to enable relay delivery.** No test enquiries or activation requests are sent during development validation.

The UI distinguishes confirmed SMTP acceptance, a handoff to the relay, and database-only storage. If delivery cannot be confirmed, the visitor receives the saved enquiry reference and direct email/WhatsApp options. Enquiries are never falsely reported as delivered. Uploaded documents remain attached to the saved enquiry; users choosing a direct email are reminded to attach their file manually.

After FormSubmit activation, its optional opaque form token can be stored in the server-side `FORMSUBMIT_TOKEN` environment variable. Never expose it in client code. Check the provider's delivery behavior with a genuine enquiry before advertising automated email delivery as operational.

### Optional authenticated SMTP

For direct email delivery, configure these server-side environment variables:

- `SMTP_HOST`
- `SMTP_PORT` (defaults to 587; port 465 enables implicit TLS)
- `SMTP_USER`
- `SMTP_PASSWORD` (or `SMTP_PASS`)
- `SMTP_FROM` (a sender approved by the mail provider)

The visitor's email becomes Reply-To; the recipient is always the official company Gmail address. SMTP failure falls back to the form relay. No credentials are hardcoded. An optional `RATE_LIMIT_SECRET` salts the hashed network identifier used for rate limiting.

## PostgreSQL

The connection is configured in `src/db/index.ts` using `DATABASE_URL`. The `falah_enquiries` table is defined in `src/db/schema.ts`. Use Drizzle Kit to apply the schema after the local environment has been bootstrapped.

The form validates required contact details, supported service/budget/timeline choices, consent, message length, file extensions, basic file signatures, and the 5 MB attachment limit. UUID request keys make retries idempotent. A database-backed hourly rate limit and a honeypot reduce casual abuse. For high-volume public deployment, add managed perimeter rate limiting and a challenge service as appropriate.

Enquiry records include personal information and document content. Restrict database access and establish an operational retention/deletion policy. Review the privacy policy with the business before public launch. Do not send sensitive records through the enquiry form.

## Content

- Company details, project links, service planning estimates, and FAQs: `src/lib/site-data.ts`
- Homepage and accessible dialogs: `src/components/`
- Styling and responsive layouts: `src/app/globals.css` and `src/app/refinements.css`
- Project enquiry: `POST /api/enquiries`
- Plain-language policies: `/privacy` and `/project-terms`
- Downloadable terms-of-reference outline: `/project-brief-template.txt`
- Health check: `/api/health`

The vector brand mark is a web recreation based on the supplied logo. Project visuals are custom illustrative concepts, not screenshots; authenticated client pages were not accessed. Any person shown in concept artwork is illustrative rather than a verified client portrait. Planning prices are indicative only and require a written, mutually accepted quotation.

## Deploying to cPanel

See `DEPLOY-CPANEL.md`. In short: create the PostgreSQL table with `deploy/schema.sql`, run `node scripts/package-cpanel.mjs` locally to produce `deploy/falah-solutions-cpanel.zip`, extract it into a folder such as `~/falah-app`, and create a Node.js application in cPanel with `server.js` as the startup file and `DATABASE_URL` as an environment variable. The packaging script sets `DEPLOY_TARGET=cpanel`, which switches `next.config.ts` to standalone output with unoptimised images; the normal `npm run build` / `npm start` flow is unchanged.

## Verification

Run Next.js route type generation, TypeScript checking, and the production build. Use the platform-managed build/start workflow for the final production server and health check. Browser smoke tests exercise responsive layouts, filters, dialogs, field validation, and direct contact links without sending fictional emails to the company's inbox.