How nawashiro/nos-hagaki works
Project type and purpose
• This is a full-stack web application built with Next.js (App Router) that serves as a Nostr client in which users are mapped to random points on Earth and message delivery is delayed based on geographic distance.
• It uses React server and client components, Prisma for database modeling and migrations, Redis utilities for caching or coordination, and serverless API routes plus a cron job for batch dispatch.
File structure
• Top-level “app” directory: Next.js page and layout routes, split into pre-login and post-login flows, with subfolders for simple and timeline layouts, mailbox (“postoffice”), profile editing, search, settings, etc.
• “app/api”: serverless routes: a cron entrypoint + a post-insert endpoint.
• “components”: reusable UI components for cards, dialogs, maps, buttons.
• “prisma”: schema.prisma & migrations → relational DB (likely PostgreSQL).
• “src”: domain utilities: NDK singleton wrappers, data-fetching, geo lookups, Redis helpers.
• Config files: next.config.js, tsconfig.json, tailwind.config.ts, postcss.config.js.
• Static assets: public/geojson map data, public/img.
• Middleware (middleware.ts) for auth/redirects.
README for additional insights
• Confirms use of NIP-07 browser extension for authentication.
• Mentions batch send logic (“一日に一度バッチ処理する”).
• Roadmap indicates core features completed: timelines, post drafting, send confirmation, profile, search, follow lists, distance/time calculation.
Main components & their interactions
a. Frontend (Next.js)
• App router pages: login, timelines, post-draft editor, confirmation, complete screens, profile, search, settings.
• UI components render posts, profiles, interactive maps, dialogs.
• Client components call serverless API endpoints or directly import shared “src” utilities for real-time fetch via NDK.
b. API layer (serverless functions)
• /api/post-insert: inserts outgoing messages into a “send queue” in the database.
• /api/cron: invoked via Vercel cron to process the queue and forward messages through NDK.
c. Database (Prisma)
• Stores user mappings, draft posts, send-queue records, follow relationships, settings.
d. Redis
• Caching of geo lookups, rate-limiting, possibly coordination locks for cron jobs.
e. External services
• Nostr network via NDK (NDKSingleton, ServerNDKSingleton).
• GeoJSON data for world map.
Architectural patterns & design principles
• Separation of concerns: UI in “components”, routing in “app”, domain logic in “src”, persistence in Prisma/Redis.
• Serverless micro-endpoints for side effects.
• Batch processing via scheduled cron function.
• React Server Components for server-side rendered content.
• Client Components for interactivity (map, dialogs).
• Singletons for Nostr event streams.
Detail
• Layout (simple, timeline), each API route, and both data-insertion and data-dispatch paths.
• Middleware at the edge for auth/redirect.