How tres-joli/metapress works
MetaPress is a single full-stack web application organized as a TanStack Start app inside a Turborepo monorepo. The repo is centered on apps/web, which contains the browser UI, server routes/API handlers, domain services, database access, and shared validation/types. There is no separate backend service in the tree; the application server, API endpoints, and SSR route handlers live together in the same app.
At a high level, the architecture has these main layers:
1. Presentation layer
2. Route and request orchestration layer
3. Domain/service layer
4. Persistence and infrastructure layer
5. Shared contracts and utilities
1) Presentation layer
The React UI lives in apps/web/src/components and apps/web/src/routes.
The UI is split into:
• generic UI primitives under components/ui
These are the reusable shadcn/Radix-style controls such as buttons, dialogs, inputs, drawers, tooltips, skeletons, and so on.
• layout/navigation components under components/sidebar, footer.tsx, theme-toggle.tsx, etc.
• domain-specific widgets such as:
- content-editor.tsx and content-viewer.tsx
- comment.tsx
- like.tsx
- share.tsx
- author.tsx
- user-grid.tsx, grid.tsx, list variants
- auth/account controls like logout.tsx, delete-user.tsx, edit-delete.tsx
• provider wrappers in components/providers
- session provider
- alert provider
- root providers composition
These components are what the route pages assemble into actual screens.
The route tree shows the app’s top-level UX boundaries:
• public/auth flows under routes/(auth)
- sign in
- sign up
- forgot password
- reset password
• protected application flows under routes/(protected)
- feed
- browse
- create blog
- edit blog
- account/profile
- liked posts
- admin dashboard
- user blog pages under /$username and /$username/$blogid
• public informational pages:
- home
- about
- contact
- policies
This split is important architecturally: public routes are unauthenticated, protected routes are guarded, and admin routes are a stricter subset.
2) Route and request orchestration layer
TanStack Router/TanStack Start are the main orchestration mechanism.
Routes do not appear to fetch data directly from ad hoc client-side fetch calls; instead, they rely on server query options and loader prefetching. The README confirms the pattern:
• route loaders prefetch data using context.queryClient.ensureQueryData(...)
• components consume that data via useSuspenseQuery(...)
This creates a clear request/data flow:
• route match happens
• loader prefetches server query data
• React Query cache is populated
• the page component reads from the cache with suspense
That pattern is used throughout the protected content areas like feed, profile, blog detail, and admin views.
There is also route-level request handling for:
• auth callback flow in routes/callback/oauth.tsx
• API endpoints under routes/api
• middleware-based protection in src/middleware/auth.ts
• root app shell in routes/__root.tsx
• protected route wrapper in routes/(protected)/route.tsx
• auth route wrapper in routes/(auth)/route.tsx
• admin wrapper in routes/(protected)/admin/route.tsx
3) Domain/service layer
The server side is organized by domain under src/server. Each domain generally has the same shape:
• *.controller.ts
entry points from routes/API handlers
• *.service.ts
business logic
• *.repository.ts
database access
• *.query.ts
React Query option factories for SSR/client data fetching
• *.schema.ts
request/response validation with Zod-style contracts
• *.error.ts
domain-specific error types
• *.type.ts / *.types.ts
domain typings
The major domains are:
• auth
• blog
• comment
• user
• general
• image
• mail
• cache
• mcp
This organization is a major architectural boundary. UI code and route handlers should depend on controllers/query helpers, not on database tables directly. Repositories isolate DB access. Schemas validate inputs at the edge. Services contain the actual business rules.
Blog domain
The blog subsystem is the core of the product:
• create/edit/fetch blog posts
• list feeds and browse pages
• fetch blog detail by slug/id
• manage blog metadata and content
• likely integrate likes, comments, author data, and cache
Comment domain
Handles:
• comment creation
• comment listing
• moderation/validation
• comment data joins with blog and user
User domain
Handles:
• profiles
• usernames
• role info
• liked posts
• admin/user separation
• profile/account-related flows
General domain
Usually used for cross-cutting non-resource-specific app logic, likely site-wide lookups and aggregates.
Image domain
A critical subsystem for content moderation and media handling:
• image upload
• image validation
• NSFW detection
• image-related response contracts
Mail domain
Supports transactional email flows such as:
• password reset
• verification
• account-related notifications
Cache domain
Wraps Redis usage:
• cache keys
• TTLs
• cache service abstraction
MCP domain
Exposes Model Context Protocol tool schemas and handlers for AI integrations.
4) Persistence and infrastructure layer
Database
Database code lives in src/db:
• schema.ts
• relations.ts
• defaults.ts
• snowflake.ts
• index.ts
This is Drizzle ORM over PostgreSQL. The data model in the README indicates the core tables/entities are:
• users
• blogs
• comments
• likes
• migrations
The presence of relations.ts implies the app uses explicit relational mapping for joins and eager relationships across users, blogs, comments, and likes.
drizzle.config.ts and the root docs indicate schema migration and push workflows are part of the architecture.
Cache
Redis is a first-class infrastructure dependency, not just an optional optimization:
• src/lib/redis.ts
• src/server/cache/*
The cache layer likely supports feed/blog/user lookups, rate limiting, and sync jobs. The repo also includes a cron endpoint for syncing likes, which suggests some materialized or periodically reconciled state.
Auth
Authentication is built around Better Auth:
• src/lib/auth.ts
• src/lib/auth-client.ts
• src/server/auth/auth.controller.ts
• routes/api/auth/$.ts
• OAuth callback route in routes/callback/oauth.tsx
The auth system is split between:
• client session state
• server auth handlers
• protected route middleware
• API handlers for auth-specific endpoints
This means auth is both a routing concern and a domain concern.
Image moderation and uploads
The content pipeline includes:
• upload support
• Cloudinary integration
• NSFW detection using a local model asset at public/models/320n.onnx
• profanity filtering via src/lib/profanity.ts
So image/content safety is not just cosmetic; it is part of the server-side validation/moderation pipeline before content is accepted or published.
MCP integration
There is an AI/tooling boundary exposed through Model Context Protocol:
• route handlers under routes/api/mcp/$.ts
• schema in src/server/mcp/mcp.schema.ts
The README says there are HTTP, SSE, and WebSocket transports. That means the app exposes a tool-facing API separate from the normal user-facing UI/API flow.
Data flow across the system
Blog creation/editing flow
1. A protected route renders the editor UI.
2. The editor component collects rich text, embeds, images, and metadata.
3. Client-side utilities perform slugging, profanity filtering, and content helpers.
4. Image upload goes through the image subsystem, which can moderate and push assets to Cloudinary.
5. The route/controller validates input through shared/server schemas.
6. The blog service persists data through the repository into PostgreSQL.
7. Cache entries may be invalidated or refreshed in Redis.
8. The page/feed queries read from the server query layer and React Query cache.
Reading a feed/blog/profile
1. A route loader prefetches query data.
2. Query helpers call controllers/services.
3. Controllers read from repositories and may consult cache.
4. The response is hydrated into the client cache.
5. The UI renders via suspense using shared data.
Commenting/liking
1. Client interaction happens in comment.tsx or like.tsx.
2. The corresponding server domain validates and persists the action.
3. Likes may be synced periodically via routes/api/cron/sync-likes.ts.
4. Related feed/profile counts are refreshed through cache-aware query paths.
Auth flow
1. Public auth routes render sign-in/sign-up/reset forms.
2. Better Auth handles credential/OAuth mechanics.
3. API auth routes and callback routes complete the handshake.
4. Session state is provided to the UI through the session provider.
5. Protected routes use auth middleware to block unauthenticated access.
Admin flow
1. Admin routes are nested under the protected area.
2. Access is role-gated, based on user role in the database/session.
3. Admin dashboard components call the same domain service layer, but with elevated permissions and moderation actions.
Shared contracts and boundary enforcement
The src/shared directory is a deliberate architecture boundary between client and server:
• shared auth schemas/types/constants
• shared blog schemas/constants
• shared user schemas/constants
• common schemas/types
• shared error types
This means validation and domain shapes are not duplicated across route and server code. The same schemas/types likely define:
• input validation
• request payload shape
• response shape
• consistent error reporting
domain-error.ts and unique-violation.ts show that domain failures are normalized rather than leaking raw database or framework errors into the UI.
Supporting utilities and runtime concerns
A number of src/lib modules act as cross-cutting helpers:
• env.ts for environment parsing
• utils.ts for general helpers
• slugify.ts
• hashids.ts
• redis.ts
• content/utils.ts
• image/*
• profanity.ts
These utilities support the higher-level domains rather than representing separate subsystems.
Deployment/runtime shape
The repo is built for:
• Bun runtime/package management
• Vite-based dev/build
• TanStack Start SSR/full-stack rendering
• Vercel deployment
• Docker compose for local PostgreSQL/Redis
So operationally, the app expects:
• a web server that can serve SSR routes and API endpoints
• PostgreSQL for persistence
• Redis for caching and possibly rate-limiting/session-related support
• Cloudinary for media storage
• optional email and OAuth providers
• MCP endpoints for AI/tool integrations
Diagram-worthy boundaries to highlight
If you are drawing an architecture diagram, the main boundaries are:
• Browser UI vs. server routes
• Public/auth routes vs. protected/admin routes
• Route handlers vs. domain services/controllers
• Domain services vs. repositories/DB
• App data vs. shared schemas/types
• Primary DB vs. Redis cache
• User-generated content pipeline vs. moderation/image services
• Standard app API vs. MCP tool API
• Auth/session boundary spanning client provider, middleware, and server auth handlers
In short, MetaPress is a monolithic full-stack blogging platform with a clean domain-oriented server structure, SSR/query-prefetch-driven pages, authenticated protected route groups, Drizzle/Postgres persistence, Redis caching, Cloudinary/media moderation, Better Auth-based auth, and a separate MCP integration surface for AI tooling.
Main entry points: blog.controller.ts Blog domain · common.schema.ts Shared schemas · user.controller.ts User domain · schema.ts Database
Components 22
Presentation
React UI components and route screens
- UI components · Reusable primitives, layout pieces, and domain widgets
apps/web/src/components/ui/button.tsx - Content views · Editor, viewer, like/share, comment, author, and content-specific widgets
apps/web/src/components/content-editor.tsx - Account UI · Profile, logout, delete-user, and related account controls
apps/web/src/components/logout.tsx - Session provider · Root client-side session and alert provider composition
apps/web/src/components/providers/session-provider.tsx
Routing
TanStack Start route shells, loaders, middleware, and APIs
- App shell · Root layout, providers, and global app wiring
apps/web/src/routes/__root.tsx - Public routes · Home and informational pages plus auth entry points
apps/web/src/routes/index.tsx - Protected routes · Authenticated app pages for feed, browse, profiles, blog actions, and account areas
apps/web/src/routes/(protected)/route.tsx - Admin routes · Admin-only wrapper and dashboard area
apps/web/src/routes/(protected)/admin/route.tsx - Auth routes · Sign-in, sign-up, reset-password, and auth callback flow
apps/web/src/routes/(auth)/route.tsx - API routes · Auth, cron, and MCP endpoint surface
apps/web/src/routes/api/auth/$.ts
Server domains
Domain controllers, services, queries, and repositories
- Blog domain · Blog controllers, services, queries, repository, and schema boundary
apps/web/src/server/blog/blog.controller.ts - Comment domain · Comment creation, listing, validation, and persistence
apps/web/src/server/comment/comment.controller.ts - User domain · Profiles, usernames, roles, and account-related data access
apps/web/src/server/user/user.controller.ts - General domain · Site-wide query and service layer for shared app operations
apps/web/src/server/general/general.controller.ts - Image domain · Upload, validation, and NSFW/moderation pipeline for media
apps/web/src/server/image/image.controller.ts - Mail domain · Transactional email templates and delivery logic
apps/web/src/server/mail/mail.service.ts - MCP schema · Model Context Protocol tool-facing schema surface
apps/web/src/server/mcp/mcp.schema.ts
Infrastructure
Database, cache, auth, media, and runtime helpers
- Database · Schema, relations, defaults, and database access layer
apps/web/src/db/schema.ts - Redis cache · Cache keys, TTLs, and Redis-backed application cache
apps/web/src/server/cache/cache.service.ts - Auth core · Server/client auth adapters and middleware-protected session boundary
apps/web/src/lib/auth.ts - Media tools · Slugging, profanity filtering, upload helpers, and image moderation support
apps/web/src/lib/image/upload-image.ts
Shared contracts
Cross-boundary schemas, types, and error shapes
- Shared schemas · Shared auth, blog, user, common schemas, constants, and domain errors
apps/web/src/shared/common/common.schema.ts
Connections 24
- App shell → UI components: composes · Root app shell mounts global providers and common UI building blocks
- App shell → Session provider: wraps · Provides session and alert context to the app
- Public routes → UI components: renders · Public and auth pages assemble reusable UI primitives
- Auth routes → Session provider: uses · Auth pages rely on session-aware client state
- Protected routes → Content views: renders · Protected screens use domain-specific content widgets
- Protected routes → Account UI: renders · Account and profile flows use account controls
- Admin routes → User domain: calls · Admin views use elevated user-management operations
- API routes → Blog domain: calls · HTTP endpoints dispatch into domain controllers
- API routes → Comment domain: calls · HTTP endpoints dispatch into domain controllers
- API routes → MCP schema: exposes · MCP route serves tool schema and transport handlers
- Blog domain → Database: persists via · Blog repository reads and writes PostgreSQL through Drizzle
- Comment domain → Database: persists via · Comment repository stores discussion data
- User domain → Database: persists via · User repository reads profiles, roles, and account data
- Blog domain → Redis cache: uses · Blog reads and invalidations go through Redis-backed cache
- User domain → Redis cache: uses · User/profile queries may be cache-aware
- Blog domain → Image domain: depends on · Blog creation/editing pipelines use media validation and uploads
- Image domain → Media tools: uses · Image moderation and upload utilities support the media pipeline
- Blog domain → Shared schemas: validates with · Domain input and response shapes are shared across client and server
- Comment domain → Shared schemas: validates with · Comment contracts are shared at the boundary
- User domain → Shared schemas: validates with · User/auth/profile contracts are shared at the boundary
- Auth core → Auth routes: backs · Auth routes and callbacks rely on the auth core
- Auth core → Protected routes: guards · Middleware enforces authenticated access to protected areas
- Mail domain → Shared schemas: uses · Mail flows share validated payload and error shapes
- Database → Shared schemas: aligns with · Database domain errors and types map to shared contracts