Skip to content

Latest commit

 

History

History
191 lines (120 loc) · 7.38 KB

README.md

File metadata and controls

191 lines (120 loc) · 7.38 KB

MetaSSR: Production-Grade AI-Powered SSR Web Applications

GitHub Stars License Last Commit GitHub Issues AI-Ready AI-Ready Testing TypeScript Next.js Prisma

MetaSSR is an opinionated template for building AI-ready, multi-tenant, server-side rendered web applications with Next.js.

MetaSSR empowers developers to create augmented intelligence systems and agentic workflows by seamlessly integrating single or multimodal ML models into production-ready SSR apps — all with strict type safety, declarative patterns, comprehensive testing, and multi-tenant authorisation baked in.

🎯 Why MetaSSR?

Multi-Tenant Data Model and Auth

Streamlined three-tier roles (OWNER/EDITOR/VIEWER) enable zero-friction onboarding (auto-OWNER status for creators), instant team collaboration with role-based permissions, and predictable access control — covering 90% of SaaS use cases without complexity.

Rapid Integration

Deploy ML models (LLMs, vision, speech, etc.) as API endpoints with type-safe, declarative schemas — no boilerplate!

Hybrid Architecture

Combine deterministic SSR logic with dynamic streaming AI agents in a unified Next.js framework.

Multimodal Ready

Process text, images, and structured data in cohesive workflows (e.g., RAG pipelines with real-time UI updates).

Testable by Design

Built-in support for mocking services and containerised testing.

🧩 Use Cases

  • Agentic Workflows: Chatbots with memory, autonomous research agents

  • Augmented Interfaces: Real-time document analysis + SSR rendering

  • Multimodal Pipelines: Vision + text models with unified API contracts

✨ Key Features

  • Modular Monolith Architecture - Well-organised codebase with clear separation of concerns

  • Type-Safe Development - Full TypeScript support end-to-end

  • Multi-Tenant Data Model and Auth - Role-based permissions, automatic tenant data isolation (zero-trust defaults), JWT-powered context, and 🚧 full audit logs

  • Declarative Patterns - Structured declarations over imperative code

  • Self-Documenting Code - Emphasis on semantic, declarative patterns

  • Testing Pyramid - Robust test coverage (Unit → Integration → E2E)

  • BDD-Oriented - Behaviour-Driven Development with *.spec.ts focus

  • Zero-Config Instrumentation - Built-in tracing to capture response latency; AI prompts and token usage, etc.

🦾 AI Superpowers

  • 🚧 Agentic Workflow Engine - Build scalable, autonomous AI processes using built-in state management, asynchronous queue processing, and real-time event signaling for seamless multi-step orchestration.

    • Cost Controls - Automatic rate limiting and spend tracking per model

    • Fallback Strategies - Configurable failover for unreliable model APIs

  • 🚧 SSR + Streaming AI - Serve static shells while streaming model responses

  • 🚧 Deterministic Caching - Versioned outputs for reproducible AI results

  • 🚧 Benchmarking Suite - Compare model performance across deployments

🛠️ Technical Stack

Core Infrastructure

  • Frontend: Next.js 13+ (App Router)
  • Relational DB: PostgreSQL (Prisma ORM)
  • NoSQL DB: MongoDB (Model abstraction)
  • API: Declarative schema-validated endpoints

Testing Suite

Test Type Location
Unit tests/unit/frontend, tests/unit/backend
Integration tests/integration/frontend+api, tests/integration/api+db
E2E tests/e2e

🛡️ Testing Strategy

We follow the Testing Pyramid approach with Behaviour-Driven Development (BDD) principles:

 E2E (critical paths; few tests)
       /         \
 Integration      \
     /             \
Unit Tests (foundation; many tests)

▶ Full Testing Documentation

🚀 Getting Started

Prerequisites

  • Node.js 18+
  • Docker
  • PostgreSQL & MongoDB (or use provided Docker setup)

Setup

  1. Environment Configuration

    cp .env.example .env
# Edit .env with your configuration

  2. Launch Infrastructure

    cd infra
docker-compose up -d

  3. Database Initialisation

    # One-time setup
cd infra/scripts
./execute.sh 00-initialise-db.sql

# Apply Prisma migrations (always run after schema changes)
npm run resync-db

# Create server user (always run after Prisma migrations)
./execute.sh 01-create-user-for-server.sql

  4. Development Server

    npm run dev

    Open http://localhost:3000 in your browser.

🧪 Testing Commands

Command Description
test:unit:frontend Run unit tests for frontend components
test:unit:backend Run unit tests for backend modules
npm test:integration:frontend+api Run integration tests to test interaction of frontend components with API server
npm test:integration:api+db Run integration tests to test interaction of API server with other backend services such as databases
npm test:e2e Run end-to-end tests

📚 Learning Resources

Core Technologies

🤝 Contributing

Contributions are welcome!

Please open an issue or PR for any improvements.

💖 Sponsor This Project

Help us build the future of AI-powered SSR:

📄 License

MIT