SessioFlow

A Call-for-Papers (CfP) platform built with Next.js, designed to help organizers manage conferences, proposals, and speaker scheduling.

📚 Documentation

Documentation Generation Workflow

When creating documentation for SessioFlow, follow this recommended order:

Step 1: Inception (Product Discovery)
         ↓
Step 2: Flow Documentation (Reveals Entities)
         ↓
Step 3: Entity Lifecycle (Define Entities)
         ↓
Step 4: More Flows (Reference Existing Entities)

Step-by-Step Process

1. Inception Phase (docs/inception/)

Complete Inception Steps 1-8 (Product Vision → MVP Canvas)
Step 6: User Journey Mapping identifies all journeys (J1-J5)
Step 7: Features & Sequencing defines MVP scope

2. Flow Documentation (docs/product/bounded-contexts/{context}/flows/)

Start with Journey 1 (e.g., Setup Conference)
Use create-flow-documentation skill to generate flow specs
Flow reveals which entities are needed (Conference, CfpConfig, etc.)
Extract Business Rules (BR-XXX) and Invariants (INV-XXX)

3. Entity Lifecycle Documentation (docs/product/bounded-contexts/{context}/entities/)

Create entity docs based on entities revealed in flows
Use create-entity-lifecycle skill to generate entity specs
Define state machines, transitions, and domain methods
Extract additional BRs and INVs if needed

4. Additional Flows (docs/product/bounded-contexts/{context}/flows/)

Document remaining journeys (J2-J4)
Reference existing entity lifecycle docs
Extract BRs and INVs as needed

Documentation Structure

docs/
├── inception/                    # Inception workshop outputs
│   ├── 1-product-vision-and-boundaries.md
│   ├── 2-tradeoffs.md
│   ├── 3-personas/
│   ├── 4-empathy-map.md
│   ├── 5-brainstorming.md
│   ├── 6-user-journeys/           ← START HERE
│   ├── 7-features-and-sequencing.md
│   └── 8-mvp-canvas-definition.md
│
└── product/                      # DDD documentation
    ├── bounded-contexts/
    │   └── conference/
    │       ├── flows/             ← Create flows first (reveals entities)
    │       │   └── journey-01-setup-conference.md
    │       ├── entities/          ← Then create entities
    │       │   ├── conference.md
    │       │   └── cfp-config.md
    │       ├── business-rules/    ← Extracted from flows/entities
    │       │   └── BR-001-*.md
    │       └── invariants/        ← Extracted from flows/entities
    │           └── INV-001-*.md
    └── flows/                    # Flow catalog
        └── README.md

AI Skills for Documentation

SessioFlow provides two AI skills to help generate documentation:

Skill	Purpose	Triggers When You Say
create-flow-documentation	Generate user journey flows	"Create flow for Journey 2", "Generate flow specification"
create-entity-lifecycle	Generate entity specs	"Create entity lifecycle for Conference", "Document the Submission entity"

Both skills are self-contained with all templates and guidelines bundled.

Documentation Workflow Diagram

flowchart TB
    subgraph Inception["Inception Phase"]
        A["Inception Steps 1-8"] --> B["Step 6: User Journey Mapping"]
        B --> C["Step 7: Features & Sequencing"]
    end

    subgraph FlowDocs["Flow Documentation"]
        D["Create Flow 1<br/>(Journey 01: Setup Conference)"] --> E["Extract BRs & INVs<br/>from flow steps"]
        E --> F["journey-01-setup-conference.md"]
    end

    subgraph EntityDocs["Entity Lifecycle Documentation"]
        G["Create Entity Lifecycle<br/>(Conference, CfpConfig)"] --> H["Extract BRs & INVs<br/>from entity constraints"]
        H --> I["conference.md, cfp-config.md"]
    end

    subgraph BRINV["Business Rules & Invariants"]
        J["business-rules/BR-XXX-*.md"]
        K["invariants/INV-XXX-*.md"]
    end

    subgraph AdditionalFlows["Additional Flows"]
        L["Create Flow 2-4<br/>(Reference Existing Entities)"] --> M["journey-02-04.md"]
    end

    %% Connections
    C --> D
    F -.-> G
    G -.-> L
    E -.-> J
    E -.-> K
    H -.-> J
    H -.-> K
    M -.-> J
    M -.-> K

    %% Styling
    style Inception fill:#e3f2fd
    style FlowDocs fill:#c8e6c9
    style EntityDocs fill:#fff9c4
    style BRINV fill:#f3e5f5
    style AdditionalFlows fill:#ffe0b2

Legend:

🔵 Inception - User journey identification
🟢 Flow Docs - Journey specifications with diagrams
🟡 Entity Docs - Entity state machines and constraints
🟣 BR/INV - Extracted business rules and invariants
🟠 Additional Flows - Reference existing entities

What Feeds Entity Lifecycle Creation?

Entity lifecycle documentation is created from multiple input sources:

Document	What It Provides	Example
Flow Documentation (Primary)	Entity behaviors, state transitions, domain methods	Flow shows `Conference.publishCfp()` → Entity needs `publishCfp()` method
Journey Mapping (Step 6)	Entity requirements from user needs	"Create conference" → Need Conference entity
Features & Sequencing (Step 7)	Feature scope and entity relationships	"CfP Management" → Need Conference + CfpConfig entities
MVP Canvas (Step 8)	Entity constraints and priorities	MVP scope limits Conference to 5 states

Extraction Process:

Flow: Journey 01 - Setup Conference
    ↓
Identifies: Conference entity with states DRAFT → CFP_OPEN
    ↓
Reveals: Methods create(), publishCfp(), closeCfp()
    ↓
Creates: conference.md with state machine and domain methods
    ↓
Extracts: INV-001 (state machine), BR-001 (date validation)

Why Flow First?

Flows reveal what entities are actually needed
Flows show how entities behave in real scenarios
Flows identify which state transitions matter
Flows expose edge cases that become invariants

Entity Lifecycle Template Uses:

State Machine from flow transitions
Domain Methods from flow steps
Constraints from flow validations
Business Rules from flow edge cases

Business Rules & Invariants Extraction

Both flows and entities automatically extract Business Rules (BR) and Invariants (INV) during creation.

Source	What It Extracts	Example
Flow Creation	Rules governing flow steps, validations, edge cases	`BR-001: Cfp Dates Must Be Valid` (from flow validation step)
Entity Lifecycle	Rules governing state transitions, domain methods, constraints	`INV-001: Conference State Must Follow State Machine` (from entity state machine)

Process:

Flow Creation:
  Journey Steps → Identify validations/edge cases → Extract BRs/INVs → Link in flow

Entity Lifecycle:
  Entity Definition → Identify constraints/methods → Extract BRs/INVs → Link in entity

Output Structure:

docs/product/bounded-contexts/conference/
├── flows/
│   └── journey-01-setup-conference.md  → Links to: BR-001, INV-002
├── entities/
│   ├── conference.md                   → Links to: INV-001, BR-004
│   └── cfp-config.md              → Links to: INV-002, BR-001
├── business-rules/
│   ├── BR-001-cfp-dates-validation.md
│   └── BR-004-free-tier-conference-limit.md
└── invariants/
    ├── INV-001-state-transition-validity.md
    └── INV-002-cfp-date-order.md

Note: You don't create BRs/INVs separately - they're automatically extracted during flow and entity creation.

Architecture Decision Records (ADRs)

Key decisions that shape the SessioFlow architecture:

ADR	Status	Description
ADR-002-00	Superseded	Use Supabase for Backend and Database
ADR-002-01	✅ Approved	Amendment: DDD Abstraction Layer
ADR-002-02	✅ Accepted	Vendor Lock-in Alternatives Analysis
ADR-002-03	✅ Accepted	Authentication Strategy with DDD
ADR-004-00	Superseded	Implement Magic Link Authentication
ADR-004-01	✅ Approved	Amendment: Auth with DDD Abstraction
ADR-005-00	Superseded	Use Supabase Storage for Files
ADR-005-01	✅ Approved	Amendment: Storage with DDD Abstraction
ADR-009	✅ Approved	Adopt Domain-Driven Design (DDD) Structure
ADR-011-00	Superseded	Use Resend for Email Communications
ADR-011-01	✅ Approved (Optional)	Amendment: Optional Email Abstraction

Latest Decisions:

Authentication Strategy (ADR-004-01): Implement DDD ports & adapters pattern for vendor-agnostic authentication
Storage Strategy (ADR-005-01): Supabase Storage with DDD abstraction (swappable to Cloudflare R2)
DDD Architecture (ADR-009): Adopt Domain-Driven Design structure for long-term maintainability
Hybrid Approach (ADR-002-01): Consider Supabase Database + Auth0 + DDD abstraction for MVP

🏗️ Project Structure

SessioFlow follows Domain-Driven Design (DDD) principles with a split monorepo structure that enables independent deployment and backend stack swapping:

sessioflow/
├── apps/
│   ├── backend/                  # Backend service (Node/Go/Kotlin)
│   │   ├── src/
│   │   │   ├── modules/
│   │   │   │   ├── conference/   # Bounded context
│   │   │   │   │   ├── domain/   # Domain layer (immutable)
│   │   │   │   │   ├── application/  # Application layer
│   │   │   │   │   ├── infrastructure/ # Infrastructure layer (swappable)
│   │   │   │   │   └── interfaces/
│   │   │   │   │       └── api/    # API contracts (backend-specific)
│   │   │   └── shared/           # Shared backend utilities
│   └── frontend/                 # Next.js frontend
│       └── src/
│           ├── app/              # Next.js pages
│           ├── components/       # UI components
│           └── modules/          # Frontend modules
│               └── conference/
│                   └── interfaces/web/  # React components
│
├── packages/                     # Shared packages (utils, etc.)
│   └── utils/                    # Frontend & backend utilities
└── docs/                         # Documentation

Monorepo Structure Benefits:

✅ Backend stack independence - Swap Node → Go/Kotlin without touching frontend
✅ Independent deployment - Backend and frontend can be deployed separately
✅ DDD purity - Domain/application layers are encapsulated in backend
✅ Clear ownership - Frontend and backend teams work independently
✅ Reduced migration cost - 8-14 hours for backend swap (vs 52-336 hours)

Module-Based Architecture Benefits:

✅ High cohesion - All code for a feature is together
✅ Independent modules - Change one feature without affecting others
✅ Easier navigation - Find all conference code in backend/modules/conference/
✅ Better scaling - Add features without touching existing code
✅ Clear boundaries - No accidental dependencies between features

🛠️ Tech Stack

Core Technologies

Frontend: Next.js 14+ (App Router)
Language: TypeScript (strict mode)
Database: PostgreSQL (Supabase or swappable alternative)
Authentication: Auth0 / NextAuth / Supabase (swappable via DDD abstraction)
Storage: Supabase Storage / Cloudflare R2 (swappable via DDD abstraction)
Email: Resend (with optional abstraction)
Testing: Vitest (unit), Playwright (E2E)
Architecture: Domain-Driven Design (DDD) with Ports & Adapters

Vendor Abstraction Pattern

All external dependencies use DDD abstraction to enable vendor independence:

// Domain layer defines the interface
interface AuthProvider {
  login(credentials): Promise<User>;
  logout(token): Promise<void>;
  getCurrentUser(token): Promise<User | null>;
}

interface StorageProvider {
  upload(file): Promise<UploadResult>;
  download(path): Promise<Buffer>;
  getUrl(path): Promise<string>;
  delete(path): Promise<void>;
}

// Infrastructure layer implements the interface
class Auth0Provider implements AuthProvider { ... }
class NextAuthProvider implements AuthProvider { ... }
class SupabaseStorageAdapter implements StorageProvider { ... }
class CloudflareR2Adapter implements StorageProvider { ... }

// Application layer uses only the interface
class LoginUseCase {
  constructor(private provider: AuthProvider) {}
}

Benefits:

✅ Swap providers with 8-14 hours effort (vs 52-336 hours)
✅ Vendor lock-in reduced by 85%
✅ Easy testing with mock implementations
✅ Can optimize costs by switching providers

CQRS Pattern

SessioFlow uses the Command Query Responsibility Segregation (CQRS) pattern for the application layer:

// Command (Write Operation)
export class CreateConferenceCommand {
  constructor(
    public readonly name: string,
    public readonly slug: string,
    public readonly cfpStartDate: Date,
    public readonly cfpEndDate: Date
  ) {}
}

export class CreateConferenceHandler {
  constructor(
    private conferenceRepository: ConferenceRepository,
    private uuidGenerator: UuidGenerator
  ) {}

  async handle(command: CreateConferenceCommand): Promise<Result<CreateConferenceDto>> {
    // 1. Validate command
    // 2. Create domain entity
    // 3. Persist to repository
    // 4. Return response DTO
  }
}

// Query (Read Operation)
export class GetConferenceQuery {
  constructor(public readonly id: string) {}
}

export class GetConferenceHandler {
  constructor(private conferenceRepository: ConferenceRepository) {}

  async handle(query: GetConferenceQuery): Promise<Result<GetConferenceDto>> {
    // 1. Query repository
    // 2. Map to response DTO
    // 3. Return data (no side effects)
  }
}

Benefits:

✅ Clear separation between read and write operations
✅ Response DTOs provide stable API contracts
✅ Independent optimization of reads and writes
✅ Improved testability with single-responsibility handlers
✅ Better alignment with DDD application layer

🚀 Getting Started

Prerequisites

Node.js 18+ or Bun
PostgreSQL database (Supabase or self-hosted)
Auth provider (Auth0, NextAuth, or custom)
Storage provider (Supabase Storage, Cloudflare R2, or MinIO)

Installation

# Install dependencies
npm install
# or
bun install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Run development server
npm run dev
# or
bun run dev

Environment Variables

# Database
DATABASE_URL=postgresql://user:password@host:5432/database

# Authentication (Auth0 example)
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

# Alternative: NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret

# Alternative: Supabase Auth
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

# Storage (Supabase example)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key

# Alternative: Cloudflare R2
R2_ACCOUNT_ID=your-account-id
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key
R2_BUCKET_NAME=your-bucket

# Email (Resend example)
RESEND_API_KEY=re_your-api-key

Database Setup

The project uses Drizzle Kit for database migrations. Local PostgreSQL is managed via Docker Compose.

# Start local PostgreSQL (Docker) — the compose file lives with the backend app
docker compose -f apps/backend/docker-compose.yml up -d

# Generate migration from schema (after schema changes)
npm run db:generate

# Apply migrations to database
npm run db:migrate

# Push schema directly (no migration file)
npm run db:push

# Open Drizzle Studio (database GUI)
npm run db:studio

Migration files are stored in: drizzle/

Schema is defined in: src/modules/conference/infrastructure/database/drizzle-schema.ts

📖 Development

Running the Development Server

npm run dev

Running Tests

# Unit tests (Vitest)
npm test

# E2E tests (Playwright)
npm run test:e2e

# Single test file
npx vitest run tests/unit/auth.test.ts
npx playwright test tests/e2e/auth.spec.ts

Type Checking

npm run typecheck

Linting

npm run lint
npm run lint:fix
npm run format

Building for Production

npm run build
npm run start

📋 Key Features

MVP Features (Wave 1)

✅ Conference creation and management
✅ Call-for-Papers (CFP) configuration
✅ Proposal submission by speakers
✅ Speaker profiles with profile photos
✅ Admin dashboard for organizers
✅ Row-Level Security (RLS) for data protection

Planned Features (Wave 2+)

📋 Review and scoring system
📋 Session scheduling and conflict detection
📋 Email notifications
📋 Export proposals to CSV/PDF
📋 Multi-language support

🏛️ Architecture Principles

Domain-Driven Design (DDD)

SessioFlow follows DDD principles to ensure long-term maintainability:

Domain Layer: Pure business logic, vendor-agnostic
Application Layer: Use cases and orchestration
Infrastructure Layer: External service implementations (swappable)
Interface Layer: UI and API entry points

Benefits:

✅ Clear separation of concerns
✅ Easy to test (domain logic has no dependencies)
✅ Swappable infrastructure (database, auth, storage)
✅ Scales well for complex domain features

Vendor Abstraction

All external dependencies are accessed through repository interfaces:

// Domain defines the contract
interface AuthProvider {
  login(credentials): Promise<User>;
  logout(token): Promise<void>;
  getCurrentUser(token): Promise<User | null>;
}

interface StorageProvider {
  upload(file): Promise<UploadResult>;
  download(path): Promise<Buffer>;
  getUrl(path): Promise<string>;
  delete(path): Promise<void>;
}

// Infrastructure implements the contract
class Auth0Provider implements AuthProvider { ... }
class NextAuthProvider implements AuthProvider { ... }
class SupabaseStorageAdapter implements StorageProvider { ... }
class CloudflareR2Adapter implements StorageProvider { ... }

// Application uses only the interface
class LoginUseCase {
  constructor(private provider: AuthProvider) {}
}

Benefits:

✅ Swap Auth0 for NextAuth with 1-line change
✅ Swap Supabase Storage for Cloudflare R2 with 1-line change
✅ Swap database provider with minimal changes
✅ Migration cost reduced by 85% (from 156-336 hours to 24-42 hours)

🛠️ Development & Architecture Quality Commands

# Fast Standalone Architecture Check (< 2s) for AI Agents & Developers
npm run check:arch                                # Check all domain modules
npm run check:arch packages/modules/conference   # Check target module/file

# Testing & Type Safety
npm run test                                      # Run unit test suite (Vitest)
npm run test:changed                              # Run tests for Git modified files
npm run test:architecture                         # Run full Vitest architecture test suite
npm run typecheck                                 # TypeScript type checking
npm run lint                                      # Run ESLint checks

🏛️ Automated Architecture Invariants

SessioFlow enforces strict Domain-Driven Design (DDD) rules via ts-archunit automated checks:

Domain Isolation: Domain modules (packages/modules/*/src/domain/) cannot depend on application, infrastructure, ORMs, or external UI frameworks.
Value Objects: Must have private constructor, static factory (create/fromString), get value(), and equals(other) method. Raw primitives (string, number, boolean) are forbidden in domain entity properties and factory parameters.
Domain Events: Must reside in domain/events/, end with Event, define type + timestamp, and implement toJSON() serialization for Outbox persistence.
Domain Exceptions: Must reside in domain/exceptions/, end with Error, and extend base DomainError / EntityNotFoundError.
Repositories: Repository interfaces reside in domain/, implementations reside in infrastructure/ and reconstitute entities via static .fromData(...) factory methods.

🤝 Contributing

Read the ADR documentation to understand architectural decisions
Follow DDD patterns when adding new features
Write tests for new functionality
Submit a pull request with a clear description

📄 License

MIT License - see LICENSE file for details

🔗 Resources

Architecture Documentation

External References

📞 Support

For questions or issues:

Open an issue on GitHub
Review existing ADRs for architectural context
Check the docs for detailed information

🎯 Quick Start Guide

For New Developers

Read ADR-009: Understand the DDD architecture
Read ADR-002b: Understand authentication strategy
Set up environment: Follow installation instructions above
Run tests: npm test to verify setup
Start coding: Follow DDD patterns in existing code

For Technical Decision Makers

Review ADR-002 Amendment: Understand vendor abstraction benefits
Review ADR-004 Amendment: Auth implementation details
Review ADR-005 Amendment: Storage implementation details
Consider trade-offs: Speed vs. flexibility, vendor lock-in vs. development time

Last Updated: 2026-06-11 Maintained By: Technical Team

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.aiforddd		.aiforddd
.claude		.claude
.husky		.husky
.opencode/commands		.opencode/commands
.pi		.pi
apps		apps
config/tsconfig		config/tsconfig
docs		docs
drizzle		drizzle
packages		packages
public		public
scripts		scripts
tests		tests
to-delete		to-delete
.gitignore		.gitignore
.markdown-link-check.json		.markdown-link-check.json
.markdown-lint-check.json		.markdown-lint-check.json
.markdownlint.json		.markdownlint.json
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
ScaffoldPlan.md		ScaffoldPlan.md
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
problems.md		problems.md
tsconfig.architecture.json		tsconfig.architecture.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

SessioFlow

📚 Documentation

Documentation Generation Workflow

Step-by-Step Process

Documentation Structure

AI Skills for Documentation

Documentation Workflow Diagram

What Feeds Entity Lifecycle Creation?

Business Rules & Invariants Extraction

Architecture Decision Records (ADRs)

🏗️ Project Structure

🛠️ Tech Stack

Core Technologies

Vendor Abstraction Pattern

CQRS Pattern

🚀 Getting Started

Prerequisites

Installation

Environment Variables

Database Setup

📖 Development

Running the Development Server

Running Tests

Type Checking

Linting

Building for Production

📋 Key Features

MVP Features (Wave 1)

Planned Features (Wave 2+)

🏛️ Architecture Principles

Domain-Driven Design (DDD)

Vendor Abstraction

🛠️ Development & Architecture Quality Commands

🏛️ Automated Architecture Invariants

🤝 Contributing

📄 License

🔗 Resources

Architecture Documentation

External References

📞 Support

🎯 Quick Start Guide

For New Developers

For Technical Decision Makers

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages