Architecture Workshop

This lesson is a practice run. You will architect a realistic project — a community event board — from scratch, applying every tool from this module in sequence. There is no new theory here; this is deliberate practice. Architecture is a skill, and skills are built by doing. By the end of this lesson you will have produced a complete build spec for a non-trivial project, which you can then use to build it.

The Project: Community Event Board

Here is the brief: A mid-sized neighborhood association wants a web application where residents can post upcoming events (concerts, clean-up drives, community meetings), browse what is happening nearby, and indicate whether they plan to attend. The association's administrator needs to be able to remove inappropriate posts. The app must work on mobile devices. There is no budget for paid infrastructure, so the solution must use free tiers of available services. That is everything you know. Your job is to transform this brief into a full build spec. Step 1: Extract Requirements. Read the brief carefully. Identify every behavior implied by the description. Write user stories for at least three user types: a resident who posts events, a resident who browses and RSVPs, and the administrator. Extract requirements from each story. Label each requirement F (functional) or NF (non-functional). Identify the acceptance criterion for each. Some requirements are stated explicitly: residents can post events, browse events, indicate attendance. Others are implied: users must have accounts to post (how else do we know who posted?), the administrator must log in somehow, events must have at minimum a title, date, and location, attending an event creates a record that can be undone. Find the implied requirements — they are just as real as the stated ones. Some non-functional requirements are stated: mobile compatibility. Others are implied by the constraint of free infrastructure: the solution cannot require expensive compute or bandwidth. Identify at least two implied non-functional requirements. Step 2: Define Scope. Apply MoSCoW to your requirements list. Be honest: what is the smallest version of this app that delivers the core value — residents discovering and attending local events? Everything beyond that core is at risk of scope creep. Consider what is explicitly out of scope. The brief mentions nothing about payment, event photos, maps integration, chat between attendees, or push notifications. Add these to the out-of-scope list explicitly so they cannot creep in. Step 3: Identify Components. Extract nouns from your requirements: events, users, RSVPs, administrators. Each is a candidate for a component or entity. Define the components: Event component: manages creating, reading, updating, and deleting event posts. Interface: createEvent(data), listEvents(filters), getEvent(id), deleteEvent(id). User Account component: manages registration, login, and session management. RSVP component: manages attendance records. Interface: rsvp(userId, eventId), cancelRsvp(userId, eventId), getRsvpCount(eventId). Admin component: manages moderation actions (delete event, potentially suspend user). Draw the dependency arrows: RSVP depends on User Account (must know who is RSVPing) and Event (must know which event). Admin depends on User Account (must verify admin role) and Event (must be able to delete events). Step 4: Design the Data Model. Entities: User: id, email, passwordHash, role (resident or admin), createdAt. Event: id, authorId (FK to User), title, description, location, eventDate, createdAt. Rsvp: id, userId (FK to User), eventId (FK to Event), createdAt. Unique constraint on (userId, eventId). Relationships: User has many Events (one-to-many). User has many RSVPs (one-to-many). Event has many RSVPs (one-to-many). A User's attendance at an Event is captured by the RSVP join entity. Access rules: Any authenticated user can create an Event. Any visitor can read Events. Only the event's author or an admin can delete an Event. An authenticated user can create or cancel their own RSVP. No user can see another user's passwordHash. Step 5: Choose Tools. Given the free-tier constraint: Front end: React with Vite (fast build, free to host on Vercel or Netlify free tier). Back end and database: Supabase free tier (managed PostgreSQL, built-in authentication, row-level security, REST API, generous free tier). Hosting: Vercel free tier. Key ADR: Supabase is chosen over a custom back end because the free tier includes authentication, database, and row-level security, which eliminates the need to build a separate API server. Constraint: all data access goes through the Supabase JavaScript client. No raw SQL in front-end components. Step 6: Decompose the Build. Task 1: Set up Supabase project and configure environment variables. (No dependencies.) Task 2: Create database schema — users extension (Supabase auth provides users), events table, rsvps table, RLS policies. (Depends on Task 1.) Task 3: Implement event listing page — fetches and displays all events sorted by date. (Depends on Task 2.) Task 4: Implement event creation form — authenticated users only. (Depends on Tasks 2, 3.) Task 5: Implement RSVP toggle — authenticated users can RSVP or cancel. (Depends on Tasks 2, 3.) Task 6: Implement authentication UI — sign up, log in, log out. (Depends on Task 1.) Task 7: Implement admin delete — admin role check, delete event with cascade to RSVPs. (Depends on Tasks 2, 3.) Task 8: Mobile responsiveness pass — CSS review and fixes. (Depends on Tasks 3, 4, 5, 6.)

Reviewing an Architecture

Once you have produced a first-pass architecture, conduct a review against five questions: 1. Completeness: Does every requirement map to at least one component and at least one task? If a requirement has no corresponding task, it will not get built. 2. Consistency: Do the component interfaces align with the data model? If the RSVP component's interface includes getRsvpCount(eventId), is eventId the correct identifier format consistent with the data model? Do the tasks reference the same component names used in the architecture section? 3. Feasibility: Does every task have an estimate? Do the estimates sum to something achievable in the available time? Does every tool decision satisfy the constraints (in this case, the free-tier requirement)? 4. Security: Does the access control model in the data model cover every read and write in the task list? Are there any operations that could be performed by an unauthenticated user but should not be? 5. Testability: Can every requirement be verified? Is there at least one acceptance criterion per requirement? Are the failure cases specified? For the Community Event Board: running through these questions reveals one gap — Task 6 (authentication UI) has no dependency on Task 2 (schema), but the sign-up process creates a user record. Task 6 should depend on Task 2. Catching this before building saves a debugging session. Architecture review is not a formality. It is a structured search for design bugs — and design bugs are an order of magnitude cheaper to fix than implementation bugs.