Sales & GTM

Fundraising & Ecosystem

Architecture

Feature-based mirror pattern, multi-tenant by default, type-safe end-to-end. Serverless on Vercel + Neon.

Principles

Component-driven — Radix primitives at the base, shadcn/ui atoms above, feature blocks at the top.
Feature-based — every feature is a self-contained directory; routes mirror components 1:1.
Serverless-first — Vercel + Neon Postgres, Edge runtime where Prisma isn't needed.
Type-safe end-to-end — Prisma → Zod → TypeScript with no manual handoffs.
Async-first — small PRs, documented decisions, steady progress.

Composition layers

Foundation: Radix UI → shadcn/ui → shadcn ecosystem.
Building blocks: UI → atoms → templates → blocks → micros → apps.

Mirror pattern

Every URL route produces two directories — one in app/ for routing and layouts, one in components/ for all feature logic. The 1:1 mapping means if you know the URL, you know where the code lives.

For route /abc:

app/[lang]/abc/ — page.tsx, layout.tsx
components/abc/ — content.tsx, actions.ts, form.tsx, validation.ts, types.ts, use-abc.ts, README.md

src/— Source code directory

app/— Next.js App Router (Routing & Layouts)

[lang]/— i18n support

abc/— URL route: /abc

page.tsx— Route entry point

layout.tsx— Route layout

components/— Component Logic (Mirrors app structure)

abc/— Mirrors app/[lang]/abc/

content.tsx— Page UI: headings, sections, layout

actions.ts— Server actions: validate, mutate

config.ts— Enums, option lists, defaults

validation.ts— Zod schemas & refinements

types.ts— Domain and UI types

form.tsx— Typed forms (RHF)

card.tsx— KPIs, summaries, quick actions

all.tsx— List view with table, filters

detail.tsx— Detail view with sections

column.tsx— Table column builders

use-abc.ts— Feature hooks

README.md— Feature purpose, APIs, decisions

ISSUE.md— Known issues and follow-ups

atom/— Atomic UI components

template/— Reusable layout templates

ui/— Base UI components (shadcn/ui)

Tech Stack

See /docs/stack for the canonical version table.

Standardized File Patterns

See /docs/pattern for the per-file canonical contract.

Decision Framework

Mirror-Pattern First: Every new route in app/[lang]/ must have a mirrored directory in components/
Component Reusability: Start with shadcn/ui components, extend only when necessary
File Pattern Adherence: Use standardized file names (content.tsx, action.ts, etc.)
Type-Safety Chain: Zod schemas → TypeScript types → Prisma models
Serverless Compatibility: Default to Edge runtime unless Prisma/bcrypt required
Feature Isolation: Each feature should be independently deployable and testable
Progressive Enhancement: UI → Atoms → Templates → Blocks → Micro → Apps
Developer Experience: Predictable structure, clear naming, documented decisions

Naming Conventions

See /docs/pattern for the canonical naming reference.

Critical Files Reference

File	Purpose
`src/proxy.ts`	Edge middleware: subdomain detection, RBAC, URL rewriting, custom domains
`src/auth.ts`	NextAuth: JWT callbacks, session management, redirect logic
`src/auth.config.ts`	OAuth providers: Google, Facebook, Credentials
`src/routes.ts`	RBAC matrix: role-based route protection
`src/lib/rate-limit.ts`	Rate limiting configs across routes
`src/lib/tenant-context.ts`	Tenant resolution with two-tier cache (Redis 5 min → in-memory Map 1 min)
`src/components/catalog/setup.ts`	Catalog bridge: academic structure provisioning
`src/lib/dns-service.ts`	DNS verification: multi-provider custom domains
`src/lib/security-headers.ts`	CSP, HSTS, XSS protection
`prisma/models/`	Prisma multi-file schema (see /docs/database)
`CLAUDE.md`	Project-wide architectural guidelines

Anti-patterns

Components not following mirror-pattern structure.
Monolithic components that should be decomposed.
Missing type-safety chain (Zod → TypeScript → Prisma).
Files not following standardized naming conventions.
Tight coupling between features.
Hardcoded values that belong in config.ts.
Direct database queries outside actions.ts / queries.ts.

Request lifecycle

User interacts with form.tsx; submit triggers a server action from actions.ts.
Payload is validated by the Zod schema in validation.ts.
The action calls queries.ts or actions.ts, which use Prisma against Neon with the types from types.ts.
Result streams back; a hook from use-abc.ts updates the UI.

Localhost Structure

On This Page

Principles Composition layers Mirror pattern Tech Stack Standardized File Patterns Decision Framework Naming Conventions Critical Files Reference Anti-patterns Request lifecycle

Principles

Component-driven — Radix primitives at the base, shadcn/ui atoms above, feature blocks at the top.

Feature-based — every feature is a self-contained directory; routes mirror components 1:1.

Serverless-first — Vercel + Neon Postgres, Edge runtime where Prisma isn't needed.

Type-safe end-to-end — Prisma → Zod → TypeScript with no manual handoffs.

Async-first — small PRs, documented decisions, steady progress.

Mirror pattern

For route /abc:

app/[lang]/abc/ — page.tsx, layout.tsx

components/abc/ — content.tsx, actions.ts, form.tsx, validation.ts, types.ts, use-abc.ts, README.md

src/— Source code directory

app/— Next.js App Router (Routing & Layouts)

[lang]/— i18n support

abc/— URL route: /abc

page.tsx— Route entry point

layout.tsx— Route layout

components/— Component Logic (Mirrors app structure)

abc/— Mirrors app/[lang]/abc/

content.tsx— Page UI: headings, sections, layout

actions.ts— Server actions: validate, mutate

config.ts— Enums, option lists, defaults

validation.ts— Zod schemas & refinements

types.ts— Domain and UI types

form.tsx— Typed forms (RHF)

card.tsx— KPIs, summaries, quick actions

all.tsx— List view with table, filters

detail.tsx— Detail view with sections

column.tsx— Table column builders

use-abc.ts— Feature hooks

README.md— Feature purpose, APIs, decisions

ISSUE.md— Known issues and follow-ups

atom/— Atomic UI components

template/— Reusable layout templates

ui/— Base UI components (shadcn/ui)

Decision Framework

Mirror-Pattern First: Every new route in app/[lang]/ must have a mirrored directory in components/

Component Reusability: Start with shadcn/ui components, extend only when necessary

File Pattern Adherence: Use standardized file names (content.tsx, action.ts, etc.)

Type-Safety Chain: Zod schemas → TypeScript types → Prisma models

Serverless Compatibility: Default to Edge runtime unless Prisma/bcrypt required

Feature Isolation: Each feature should be independently deployable and testable

Progressive Enhancement: UI → Atoms → Templates → Blocks → Micro → Apps

Developer Experience: Predictable structure, clear naming, documented decisions

Critical Files Reference

File	Purpose
`src/proxy.ts`	Edge middleware: subdomain detection, RBAC, URL rewriting, custom domains
`src/auth.ts`	NextAuth: JWT callbacks, session management, redirect logic
`src/auth.config.ts`	OAuth providers: Google, Facebook, Credentials
`src/routes.ts`	RBAC matrix: role-based route protection
`src/lib/rate-limit.ts`	Rate limiting configs across routes
`src/lib/tenant-context.ts`	Tenant resolution with two-tier cache (Redis 5 min → in-memory Map 1 min)
`src/components/catalog/setup.ts`	Catalog bridge: academic structure provisioning
`src/lib/dns-service.ts`	DNS verification: multi-provider custom domains
`src/lib/security-headers.ts`	CSP, HSTS, XSS protection
`prisma/models/`	Prisma multi-file schema (see /docs/database)
`CLAUDE.md`	Project-wide architectural guidelines

Anti-patterns

Components not following mirror-pattern structure.

Monolithic components that should be decomposed.

Missing type-safety chain (Zod → TypeScript → Prisma).

Files not following standardized naming conventions.

Tight coupling between features.

Hardcoded values that belong in config.ts.

Direct database queries outside actions.ts / queries.ts.

Request lifecycle

User interacts with form.tsx; submit triggers a server action from actions.ts.

Payload is validated by the Zod schema in validation.ts.

The action calls queries.ts or actions.ts, which use Prisma against Neon with the types from types.ts.

Result streams back; a hook from use-abc.ts updates the UI.

balqalam

Architecture

Principles

Composition layers

Mirror pattern

Tech Stack

Standardized File Patterns

Decision Framework

Naming Conventions

Critical Files Reference

Anti-patterns

Request lifecycle

balqalam

Architecture

Principles

Composition layers

Mirror pattern

Tech Stack

Standardized File Patterns

Decision Framework

Naming Conventions

Critical Files Reference

Anti-patterns

Request lifecycle