Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Ishaq74/concordia/llms.txt

Use this file to discover all available pages before exploring further.

​

System Architecture

​

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                       │
│                  (Astro SSR + Components)                   │
├─────────────────────────────────────────────────────────────┤
│                     Application Layer                       │
│              (Actions, API Routes, Loaders)                 │
├─────────────────────────────────────────────────────────────┤
│                      Domain Layer                           │
│        (Business Logic, Services, Permissions)              │
├─────────────────────────────────────────────────────────────┤
│                    Persistence Layer                        │
│           (Drizzle ORM + PostgreSQL Database)               │
└─────────────────────────────────────────────────────────────┘

​

SSR Architecture (Astro)

• Server-Side Rendering: Pages are rendered on the server for optimal SEO and performance
• Static Site Generation: Static pages can be pre-rendered at build time
• API Routes: Server-side API endpoints for data mutations and complex operations
• File-based Routing: Intuitive page routing based on file structure
• Component Islands: Interactive client-side components embedded in SSR pages

​

Request Flow

Client Request
      ↓
Astro Router
      ↓
Page Component (.astro)
      ↓
Data Loader (getDrizzle)
      ↓
Database Query (Drizzle ORM)
      ↓
HTML Response (SSR)

​

Domain Model

​

Core Entities

• user - User accounts (Better Auth)
• profile - Public user profiles
• user_role - Role assignments (citizen, owner, author, mediator, admin)
• organization - Organizational structures
• member - Organization membership

• blog_posts - Blog articles
• blog_translations - Multi-language content
• blog_categories - Content categorization
• blog_comments - User discussions
• blog_media - Media assets

• services_listings - Service offerings
• services_bookings - Reservations
• services_availability - Time slots
• services_reviews - User ratings
• services_categories - Service taxonomy

• notification - User notifications
• audit_log - System audit trail

​

Entity Relationships

user (1) ──→ (N) profile
     (1) ──→ (N) user_role
     (1) ──→ (N) blog_posts (as author)
     (1) ──→ (N) blog_comments
     (1) ──→ (N) services_bookings
     (1) ──→ (N) services_reviews

blog_posts (1) ──→ (N) blog_translations
           (1) ──→ (N) blog_comments
           (N) ──→ (N) blog_categories
           (N) ──→ (N) blog_media

services_listings (1) ──→ (N) services_translations
                  (1) ──→ (N) services_bookings
                  (1) ──→ (N) services_availability
                  (1) ──→ (N) services_reviews

​

Database Layer

​

Drizzle ORM + PostgreSQL

• Type-safe database queries
• Schema-first approach with TypeScript definitions
• Migration management
• Connection pooling
• Multi-environment support (local, test, production)

// Dynamic database selection based on environment
if (process.env.USE_PROD_DB === 'true') {
  url = process.env.DATABASE_URL_PROD;
} else if (process.env.USE_DB_TEST === 'true') {
  url = process.env.DATABASE_URL_TEST;
} else {
  url = process.env.DATABASE_URL_LOCAL;
}

// Connection pooling
const pool = new Pool({
  connectionString: url,
  ssl: url.includes('sslmode=require') ? { rejectUnauthorized: false } : undefined,
  max: 5,
  idleTimeoutMillis: 10000,
});

const db = drizzle(pool, { schema });

• Schemas defined in /src/database/schemas/
• One schema file per domain entity
• Centralized exports via schemas.ts
• Migrations stored in /src/database/migrations/

​

Authentication Layer

​

Features

• Multiple Authentication Methods:
  • Email/password with verification
  • OAuth providers (configurable)
  • Magic link authentication
• Session Management:
  • Secure session tokens
  • Session persistence
  • Automatic session refresh
• Role-Based Access Control (RBAC):
  • Multiple roles per user
  • Granular permissions
  • Organization-level access control
• Security Features:
  • Rate limiting
  • CSRF protection
  • Password hashing (bcrypt)
  • Email verification

​

Authentication Schema

• user - User accounts
• session - Active sessions
• account - OAuth provider links
• verification - Email verification tokens
• rate_limit - Rate limiting counters
• invitation - Organization invitations

​

Authorization Model

enum app_role {
  citizen      // Default user
  owner        // Business owner
  author       // Content creator
  mediator     // Conflict mediator
  educator     // Education module manager
  moderator    // Content moderator
  admin        // Platform administrator
}

• Middleware for route protection
• Action-level authorization
• Row-level security policies (RLS)

​

Multi-Language Routing

​

URL Structure

/{lang}/                 - Homepage
/{lang}/blog/            - Blog listing
/{lang}/blog/{slug}      - Blog post
/{lang}/services/        - Services listing
/{lang}/auth/sign-in     - Authentication

​

Implementation

• Route Pattern: /[lang]/... dynamic parameter
• Locale Detection: Browser preferences, URL parameter, user profile
• Content Translation:
  • UI translations: /src/i18n/ JSON files
  • Database translations: *_translations tables
• Locale Helper: locale-url.ts for URL generation

​

Translation Tables

• blog_translations - Blog post content
• services_translations - Service descriptions
• Future: place_translation, article_content

​

Key Architectural Patterns

​

1. Server Actions

// src/actions/blog.ts
export const actions = {
  createPost: async (data) => {
    // Validate permissions
    // Validate data
    // Perform database operations
    // Return result
  }
}

​

2. Data Loaders

// src/database/loaders/blog.ts
export async function loadBlogPost(slug: string, lang: string) {
  const db = await getDrizzle();
  return await db.query.blogPosts.findFirst({
    where: eq(blogPosts.slug, slug),
    with: {
      translations: { where: eq(translations.language, lang) },
      author: true,
      categories: true
    }
  });
}

​

3. Component Modules

src/components/
  modules/
    blog/
      cards/      - PostCard, AuthorCard
      lists/      - PostGrid, FeaturedGrid
      single/     - PostHeader, PostContent
      ui/         - CategoryBadge, ShareButtons
    services/
      cards/      - ServiceCard
      single/     - ServiceHeader, ServiceBooking

​

4. Type Safety

• Database schema → TypeScript types (Drizzle)
• API contracts with typed responses
• Component props with TypeScript interfaces

​

Performance Optimizations

• Connection Pooling: Reused database connections (max: 5)
• Cached Drizzle Instance: Single database client per process
• SSR Caching: Static page generation where appropriate
• Image Optimization: Astro’s built-in image optimization
• Lazy Loading: Dynamic imports for large components

​

Security Architecture

• Input Validation: Server-side validation for all inputs
• SQL Injection Prevention: Parameterized queries via Drizzle ORM
• XSS Protection: Automatic escaping in Astro templates
• CSRF Protection: Built into Better Auth
• Rate Limiting: Request throttling per user/IP
• Audit Logging: All admin actions logged to audit_log

​

Deployment Architecture

• Node.js: Full SSR with @astrojs/node adapter
• Vercel: Optimized for Vercel platform with @astrojs/vercel
• Static: Pre-rendered static site for CDN deployment

​

Environment Configuration

DATABASE_URL_LOCAL=postgresql://...
DATABASE_URL_TEST=postgresql://...
DATABASE_URL_PROD=postgresql://...
USE_PROD_DB=false
USE_DB_TEST=false

​

Next Steps

• Tech Stack Details - Comprehensive technology breakdown
• Project Structure - File organization and conventions
• API Documentation - API endpoints and contracts